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PREFACE 


This manual describes the IBM Instruments Computer System 9000 Operating 
System (CSOS). It consists of five chapters and five appendixes. 


®@ 


Chapter 1 -- "Introduction to the Operating System" -- describes the 
operating system and the system commands used with it. 


Chapter 2 -- "Full-Screen Editor" -- describes the main features of 
the text editor, including the various commands that can be used to 
create and edit source and text files. 


Chapter 3 -- "Computer System Macro Assembler" -- describes the 
instructions, instruction formats, addressing modes, and related 
aspects of the two-pass macro assembler that runs under the operating 
system. 


Chapter 4 -- "Linker and Library Utilities" -- describes the two 
programs available to the user for the development of modular code. 


Chapter 5 -- "Debug" -- describes the special debugging utility 
designed to run in the multitasking environment of CSOS. 


Appendix A -- "Error Messages" -- lists and defines the various error 
messages that may be generated in the operation of CSOS. 


Appendix B -- "Instruction Set Summary" -- lists the mnemonics, a 
description, and the syntax of every instruction recognized by the 
68000 assembler. 


Appendix C -- "Character Set" -- summarizes the characters, numbers, 
and symbols recognized by the 68000 assembler. 


Appendix D -- "Sampler Assembler Output" -- lists an assembler 
program. 
Appendix E -- "Examples of Linked Assembly-Language Programs' -- 


lists an ALINK-screen dialog and an output map. 


Related Publications: 


Publications that discuss related aspects of the Computer System are: 


Computer System Product Description, GC22-9183 
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Computer System Operating System Reference Manual Part 2: Assembly 
Programmer's Guide to Logical I/O and System Services, GC22-9200 


Computer System BASIC Reference Manual, GC22-9184 
Computer System FORTRAN Reference Manual, GC22-9194 
Computer System PASCAL Reference Manual, GC22-9190 


Computer System Problem Isolation Manual, GC22-9192 


Additional References: 


A good understanding of assembler language programming is assumed in much 
of this manual. There are many sources of information on the subject, 
whether formal classroom education or through use of books and other 
student material. 


A knowledge of the facility of the 68000 microprocessor is also important 
in much of this manual, especially in understanding the instruction types 
and notation conventions which apply to this microprocessor. There are 


several books available on the 68000, two of which are: 


e Motorola MC68000 
16-Bit Microprocessor User's Manual 
PRENTICE HALL, Inc., Englewood Cliffs, NJ, 1982 


e 68000 Assembler Language Programming 
by Gerry Kane, Doug Hawkins, and Lance Leventhal 
OSBORNE /MCGRAW-HILL 
Berkeley, CA, 1981 
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1.0 INTRODUCTION TO THE OPERATING SYSTEM 


The IBM Instruments Computer System 9000 (CS 9000) has a disk-based 
multitasking operating system -- CSOS -- that supports’ standard 
peripherals such as a line printer, CRT display, floppy disks, hard disks, 
and auxiliary consoles. 


This chapter is designed to get you started using CSOS. It is neither a 
tutorial on operating systems nor an exhaustive treatment of how to use or 
modify the software, but it should tell you what you need to know to begin 
working with the software. 


1.1 GENERAL INFORMATION 


1.1.1 COMMAND STRUCTURE 


— 


Commands in CSOS consist of a command name and optional parameters. Some 
commands are resident in memory and will execute immediately; others are 
transient (stored on disk) and must be loaded from disk before they are 
executed. User-defined commands are invoked by entering their full names. 
These command files must be binary type with transfer addresses (access 
type 01). If the file has a ".BIN" extension, the extension need not be 
typed. 3 


When no command is found resident or transient, the command is assumed to 
be SUBMIT and the entered data the submit file to be processed. 


Where CSOS requires numeric values, either decimal or hexadecimal 
notation may be used. Hex values must be preceded by a dollar sign (S$). 


The operator prompt is: 


O> _ 

The digit before the ">" symbol is the drive number of the default disk. 
If the user has a formatted hard-disk as drive 4, then the prompt will be 
"4>" at power on. Otherwise, the default prompt is "O>" for diskette 
systems. 
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1.1.2 NAMING FILES 


A fully specified filename consists of three fields: A volume identifier, 
a filename and an extension. When filenames are specified in system 
commands, specific delimiters must be used to separate the fields: 


1.1.2.1 Filename Format 


The standard filename format for use in system commands is either 
<volume:>filename.ext 
or 


<drive:>filename.ext 


where 

volume is a field of one to six alphanumeric characters and is always 
terminated by a colon. This field can be omitted, in which case 
the default volume is used. A volume name cannot be a single 
numeric digit. 

drive is a single digit number and is always terminated by a colon. 


This references the volume mounted in the physical drive number 
specified. 0 to 3 correspond to #FDOO to #FD03, (diskette 
drives) and 4 to 7 correspond to #HDOO to #HDO3 (hard-disk 
drives)... 

filename is a field of one to eight alphanumeric characters with the 
leading character alphabetic. It is generally followed by a 
period and the filename extension. 


ext is a field of one to three alphanumeric characters with the 
leading character alphabetic. 


EXAMPLES OF VALID FILENAMES 

INPUT.TXT DOREEN1.REL H1.H  LINDAS.FIL 
O:INPUT.TXT 1:INPUT.HEX  0:INPUT2.TED 
123456:BLUE.SRC CLYDE: TESTCASE.BIN 


VOL7 : TERRYPGM. REL POLLY : TEMPFILE.SRC 
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1.1.2.2 Entering Filenames 


To specify a file, give the volume name or disk drive number, filename, 
and extension. The following are examples of unique files: 


MASTER: INPUT . TXT 1: INPUT. TXT 4: INPUT .HEX O: INPUT2 . TXT 


The system maintains a default volume/drive. If a file is on the default 
drive, the volume name or drive number and colon may be omitted from the 
file specification. If the default drive is set to zero with the volume 
'RAM2' mounted in the drive, the following file descriptors would be 
identical: 


O:MELS.BIN MELS.BIN RAM2:MELS.BIN 


Using the SET command, the user may modify the default drive. Any drive 
in the system may become the default drive. The default volume would 
become whatever volume is mounted in the default drive. 


Note that only alphanumeric characters may appear in filenames or 
extensions. The following are invalid filenames: 


1: TERRYSFILE. HEX (name more than 8 characters) 
2:TEMP.FILE (extension more than 3 characters) 
O TEST.TMP (colon missing after drive number) 
BASIC+.BIN (+ is a nonalphanumeric character) 
JANEPROG (file extension missing) 


1.1.3 WILDCARD FEATURE 


CSOS permits manipulation of classes of files. The mechanism for forming 
such classes is called wildcarding. Two wildcard characters perform 
unique identification tasks. The asterisk (*“) matches an entire string of 
characters of arbitrary length. Since a complete filename consists of two 
strings (a name and an extension) the wildcard filename *.* expresses all 
possible filenames. The wildcard filename *.BLD expresses all filenames 
with the extension BLD. 


The second wildcard character is the question mark (?). This character 
substitutes for any single character (including any blanks the system may 
have incorporated to "fill out" the filename to its maximum legal length). 
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Hence, the filename TEST?.HEX is equivalent to TEST.HEX or TESTP HEX o¢ 
TEST2.HEX. It is not equivalent to TESTING.HEX. The filename *.* is 
equivalent to ??72777277.2???. 


The asterisk character (*) can be used to match any remainder of a string. 
When it is used in positions other than the first in a string, it is 
equivalent to the number of "?" characters that would be required to fill 
out the string (up to 8 for filenames, up to 3 for extensions). For 
example, the following wildcard file specifications match all files on the 
default drive whose names begin with the letters "WILD" and whose 
extension begins with the letter "T." 
WILD* .T* WILD???? .T* WILD???? .T?? 


NOTE: A trailing character after an asterisk will genératé a syntax 
error. 


1.1.4 CTRL-ALT-DEL FUNCTION 


There may be times when the user wishes to restart the system without 
resetting it. CSOS uses a three-key sequence as a "warm start’ mechanism: 

Ctrl-Alt-Del. This set of keystrokes causes a restart that prints the 
start-up banner, and readies the system for new commands. Any pending 
SUBMIT file is terminated, attached drives and devices become unattached, 

and the SPOOL queue becomes empty. 


WARNING: This function should be used sparingly. If used while writing 
to disk, it may result in a corrupted disk. 


1.1.5 TASKS AND MULTITASKING 


A "task" (sometimes termed "process") is a program that is run under the 
control of CSOS. In fact, parts of CSOS are themselves "tasks." Tasks 
run concurrently: that is, they appear to share the resources of the 
computer. (Such resources include the processor itself, console, memory 
areas, disk files, etc.) Each task is associated with a data structure 
called a Process Control Block (PCB), which contains fields that store 
information about the task and provide the mechanisms for the support of 
concurrency. Tasks call on the features of CSOS to gain access to system 
resources in a controlled manner. CSOS schedules tasks so as to give each 
a share of the computer's time and resources. Synchronization mechanisms 
and intertask communication channels are provided through system calls 
described in Part 2 of this manual (GC22-9200-1). 
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Each task in the system has an identifying name of up to 8 alphanumeric 
characters. This name is the means for calling upon system tasks (by 
means of system commands that will be described later in this chapter). 
No two tasks in the system may have duplicate names. No wildcarding is 
permitted in task names. 


1.1.5.1 Predefined Tasks (System and Idle) 


The task name SYSTEM is predefined. This task performs all CSOS commands 
and actually constitutes the "system" with which the user interacts. The 
SYSTEM task begins running when CSOS is started. The user may issue 
commands to DELAY or change the priority of the SYSTEM task, but should do 
so with care. 


There is a second predefined task in CSOS: the "idle" task. This task is 
an exception to the rule that tasks have names. The ‘idle’ task has no 
name and does not appear in the TASKS display, but it is always in the 
system. The "“idle’ task has the lowest priority possible -- it runs only 
when all other tasks (including SYSTEM) cannot run for some reason. The 
user cannot DELAY or KILL the "idle' task. There is no need to in any 
case, since "idle" will not run if there are any other tasks that are 
ready to run. 


1.1.5.2 Task Priority, Task Status, and Task Interrupts 


Each task has a priority value associated with it. The priority is a 
number between 1 and 127. Within CSOS, tasks are ordered by priority, the 


higher numbers run ahead of lower ones. Tasks of equal priority are 
scheduled on a round-robin basis. A task's priority is set when the task 
is created, but may be changed if desired. The default priority of SYSTEM 
is 64, while the priority of "idle" is 0. 


A maximum of thirteen tasks in addition to the SYSTEM task is allowed. 


Each task has an associated status byte. This byte indicates the current 
status of the task and may take on one of the following values: 


No task (PCB is unallocated or task has been killed) 
- Task is ready to run 

Task is delayed on a timeout 

- Task is blocked on I/O 


Wh Fr © 
! 
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4 - Task is suspended pending completion of an asynchronous 
operation. 
5 - Task is undergoing termination 


The time at which a task is created (as determined by the time-of-day 
clock) is part of the task PCB. SYSTEM is always shown at the time that 
CSOS was started or restarted. 


Tasks are switched on each real-time clock interrupt (every twentieth of a 
second). A task switch could also occur when the running task must wait 
for a system resource or I/O device. The highest-priority task on the 
ready queue (which could be the task that had been running) is dispatched 
and the new task begins its execution. This task switching is transparent 
to the user except for the time delays that become involved when more than 
one task shares the computer. If a task has a priority greater than 
SYSTEM (>64), then SYSTEM will run only when the higher-priority task is 
waiting for some system resource or [I/O device. This could make it appear 
that SYSTEM is not running at all. Similarly, if a user's task has 
priority lower than SYSTEM (<64), it may appear that the user task never 
runs. Actually, the user task runs whenever SYSTEM must wait for a system 
resource or I/O device. Task priorities must be chosen with care. 


It is possible to delay a task (make it stay off the ready queue) for a 
specified number of real-time clock "ticks.'' The DELAY command and the 
DELAY system-call provide this facility. A DELAYed task will be placed 
back on the ready queue after a specified number of "ticks." The RESUME 
command and WAKEUP system call provide a means to immediately place a 
DELAYed task back on the ready queue. These commands and system calls 
give the user more flexibility in the control of task execution. 


Tasks are started up by using the RUNTASK command with an initial 
priority. The task priority can be changed at any time by using the 
PRIlority command. 


1.1.5.3 Multitasking in a Real-time Operating System 


The attached figure shows a very simplified schematic of interactions 
between the Operating System, Input/Output device interrupts, and 
multiple tasks (either system utilities or user-written). 


A 'task' can be thought of as a program in memory which is associated with 
a major ‘job’ being done. Tasks can be creating a display, moving data 
from memory to disk, doing some calculations, using the communication 
port, etc. A task may call in other programs as part of its own operation; 
may remove itself, may suspend itself for awhile, or start up another 
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task. An application 'package', such as Chromatography, is a set of 
tasks, and are all loaded into memory (from disk) when the application is 
called for. 


Each task that is to be a part of a multitask operation is given a loading 
memory address and a priority by the author; however, this priority can be 
changed while the application is running. It can even be assigned a 
priority when the task is started from the keyboard. Tasks that are to 
run on the computer simultaneously must be in different memory areas to 
avoid an overlay of programs, and possible system crash. (See the RUNTASK 
command and the GETPCB System Call (Part 2, System Calls)). 


Each task in memory with the same highest priority is given equal time (50 
milliseconds) by the operating system. This is accomplished by the SYSTEM 
CLOCK actually interrupting the processor every 50 milliseconds. The 
interrupt service routine gives control to the task switch routine in the 
operating system. This routine looks at the current priorities of all 
active tasks and gives control to the one with the highest priority (even 
if it was the one that was just interrupted). If several tasks have the 
same high priority as the interrupted one, this one is put on the bottom 
of the list, and the next task in the list is given control. 


It would appear that a lower priority task would never get a chance, and 
that is so. However, if the higher priority tasks are ‘waiting’ for some 
input/output request to be finished, then these tasks are now on the 
‘wait' list, so the operating system gives control to the lower priority 
task. 


Since almost all programs use Input or Output (to the disk, printer, 
RS-232, etc.) eventually all tasks get completed, even ones with low 
priority. 


Be aware, however, that if you have a task that does no I/O (sometimes 
referred to as ‘CPU bound"), then you should not run it at a priority 
higher than the SYSTEM task, because the SYSTEM task will be locked out 
and you will not be able to issue commands (like KILL or PRI) to correct 
the situation. 


The set of programs for handling hardware interrupts have a priority 
higher than that of any task. Hardware interrupts signal the occurrence 
of an event or the completion of a data transfer. 


When a hardware interrupt occurs it forces the processor to stop whatever 
task is executing and to branch to one of 256 possible addresses (or 
programs). Interrupts can be ‘masked’ so that they are ignored until 
‘armed'. The interrupt programs are generally very short so that they are 
executed quickly and return control to the program which was interrupted 
(see diagram on page 1-8). 
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These hardware interrupts (if not masked) are also prioritized, so that 
even an interrupt service program can be interrupted by a higher priority 
interrupt. This does not happen too often, but the assignment of 
input/output interrupts takes some care. 


The keyboard handling is an example of the relationship between interrupts 
and tasks. When a key, or a combination of keys, is depressed, the 
processor is interrupted and the interrupt service routine for the 
keyboard transfers the data from the keyboard to a RAM ‘keyboard buffer' 
area used by the operating system. The interrupt service routine then 
returns to the system. A task, perhaps a system or a user task, waiting 
for some keyboard input, when next given a time period for execution, will 
then examine this buffer for the presence of characters. It will take 
appropriate action depending on the character(s) found there. The usual 
thing is to display what was typed, and then to execute the appropriate 
section of the program in memory. 


1.1.6 SYSTEM MEMORY POOL 


Most operating system functions require some amount of memory to 
temporarily save information. Memory for this purpose is drawn from a 
reserved system memory pool. If the system memory pool were not used, 
then each system function would have to reserve its temporary memory 
whether it was being used or not. In practice this means that large 
amounts of memory would be wasted. Since all temporary memory is 
generally not used at the same time, the reserved pool is made small so 
that more memory is available for the user. In some cases many system 
functions are required at the same time and the system memory pool is not 
large enough to accommodate all temporary memory requests. At such a time 
the user will typically receive the error message: 


MEMORY NOT AVAILABLE 
The recommended action is for you to increase the size of the system 


memory pool with the SET SM command (see Appendix F: SYSTEM MEMORY 
CONSUMPTION). 
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1.2. SYSTEM COMMANDS 


1.2.1 USER TRANSIENTS 


Any binary file (type 01) can be executed directly as part of the SYSTEM 
task. For example, if drive 1 has a program file called PGM.BIN, then the 
program can be run with the command: 


1:PGM 


The system loads the transient file into memory and jumps to its transfer 
address. (Invoking the program is thus equivalent to a LOAD command 
followed by a JUMP command.) If there is no transfer address, control 
returns to the system. Parameters required by the user transient may be 
input on the same command line that invokes it. A space, comma, or other 
nonalphanumeric delimiter must separate the parameters from the file 
specification. For example, 


1:COPY INPUT.TXT ,MYVOL: OUTPUT. TXT 


invokes the COPY program from drive 1 and specifies the input and output 
files to be used. 
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1.2.2 ATCHDEV (RESIDENT) 
The ATCHDEV command attaches a device to an existing driver that is part 
of the system. The format of the command is: 

ATCHDEV device 
where ‘device' is the name of the device to be attached. The first 
character must be a '‘'#' to indicate a device name. The next three 


characters must match the existing driver name. An error will occur if 
the driver does not support additional devices. 


ERROR MESSAGES 
SYNTAX ERROR 


The device driver may produce unique error messages. See device driver 
documentation. 
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1.2.3 ATCHDRV (RESIDENT) 


The ATCHDRV command "attaches" a device driver to the system by loading a 
binary image file (type 01) from disk and executing it. The file is 
assumed to contain device driver code. The command examines register D7.W 
on return for an indication of the driver's success at initialization. A 
nonzero value indicates failure. The format of the command is: 


ATCHDRV filename.ext 


where '‘filename.ext' is the name of the file containing the driver code. 
If no extension is specified in the filename, the command assumes '.DRV'. 


ERROR MESSAGES 


SYNTAX ERROR 

INVALID LOAD FILE FORMAT 
LOAD ADDRESS TOO LOW 

NOT ENOUGH MEMORY TO LOAD 
NO FILE TRANSFER ADDRESS 
DUPLICATE PDB NAME 
DUPLICATE EDB NAME 


The device driver being attached may produce unique error messages. See 
device driver documentation. 
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1.2.4 CLS (RESIDENT) 


The CLS command clears the displayed page of graphics memory. It should 
be used with discretion. The format of the command is: 


CLS 
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1.2.5 COPY (TRANSIENT) 


The COPY program transfers data from one device or file to another. The 
format of the command is: | | | 


COPY source,destination|;options ] 


where source and destination can be a device specification (see Part 2, 
section 1.2.5): 


#device 
or a file specification (see Part 2, Section 1.2.4): 


[volume: ] filename. ext 


Directly accessing the disk drives through their device names (#FDOO 
through #FDO3 or: #HDOO through #HDO3) is not accepted by the COPY 
command. Also, do not attempt to copy between two disks with the 
same volume identifiers. The operating system does not support 
duplicate volume identifiers mounted at the same time. 


The wildcard character asterisk (*), may be used within or in place of the 
filename, the extension fields, or both. The wildcard feature may be used 
only in a file-to-file copy. If specified, the user is prompted before 
each file is copied. If both source and destination are files, the 
following options may be chosen: 


C -- compare files. A byte-by-byte comparison is made between the two 


files specified. If a mismatch is found, the format of the output 
is: 

RELATIVE FILE 1 FILE 2 

SECTOR OFFSET BYTE BYTE 

XXXXXXXX XXXX XX XX 


All values printed are in hexadecimal. If ten or more mismatches are 
encountered, an error message is printed and the file comparison is 
aborted. 


D -- delete files without prompting. If a file already exists on the 
destination disk, it will be automatically overwritten. 


M -- specify buffer size (M=XX). The default buffer size used is from the 
buffer start to the end of user memory (APPEND). The M option 
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specifies the number of 1K-byte (i.e., 1024-byte) blocks of memory to 
be used. The buffer start address is $2000 past the program load 
address. (This can be found by typing LOAD COPY.) If COPY loads at 
SEOOO, then the buffer start address is $10000. If the user typed 
option M=50, then the buffer end address would be $1C800 (50 x 1024 = 
51200 = $C800). 


S -- create contiguous file. The output file created in a file to file 
copy will be a contiguous file. 


V -- verify destination file. File sectors are read in from the source 
disk and then written to the destination disk. To verify the file 
copy, the sectors are read back from the destination file, and 
compared with the original file sector data that has been preserved 
in memory. If a mismatch is encountered, an error message is 
printed, and the destination file is deleted. 


Y -- copy files without prompting. If copying using wildcards, all files 
will be copied without selective user interaction. If the file 
already exists on the destination disk, the user will still be 
prompted, unless the 'D' option was also specified. 


The following options are used only when outputting to a device. 


L -- append linefeed. If a record has a carriage return as a delimiter, a 
linefeed will be written following it. 


T -- truncate record. Maximum record lengths of 132 characters, will be 
truncated at 79 characters followed by a carriage return. 


When the source of data is a device, the following keyboard control 
character is accepted: 


Ctrl/D -- end of input 


When the destination of data is a device, the following keyboard control 
characters are accepted: 


Ctrl/Break -- quit 
Ctrl/Numlock -- halt until any key pressed. 


The following short-hand notations are accepted by the COPY command for 
device names: 


'#' as a source name gets input from the '#CON' device. 
'#' as a destination name outputs to the '#SCRNO' device. 
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Note: Do not use '#CNSLO' as a destination device. This is a three-line 
window at the bottom of the screen used for echoing command input 
and displaying error messages. 


If the fields following the COPY command are omitted, COPY will prompt the 
user for the desired input, as shown in the following example: 


COPY | 

ENTER SOURCE DEVICE OR FILE SPECIFICATION: *.SMP 

ENTER DESTINATION DEVICE OR FILE SPECIFICATION: TEST:*.SRC 
ENTER OPTIONS: V 

COPY (Y/N/Q) RAMVOL: GRTESTO2.SMP TO TEST : GRTESTO2.SRC ? Y 
FILE EXISTS: OVERWRITE (Y/N) TEST : GRTESTO2.SRC ? Y 

COPY (Y/N/Q) RAMVOL: PRTESTOO.SMP TO TEST : PRTESTOO.SRC ? Q 


ANOTHER COPY ? N 


This prompts the user for each file with the extension .SMP on the default 
volume (here it was RAMVOL). When the user replies ‘Y', the file is 
copied to the destination volume (TEST), with the extension .SRC. If the 
file already exists on the destination disk, the user is asked whether it 
should be overwritten. In this example, each file is verified after it has 
been copied. The abbreviations used are: Y = Yes, N=No, Q= Quit. 


EXAMPLES 
COPY 1:SAMPLE.SRC ,#PR 


copies the text file SAMPLE.SRC (file type 3) from the volume identifier 
mounted in drive 1, to the printer. 


COPY #CON, #SEROO 


transfers characters typed in from the keyboard, to the device connected 
to the serial port #SEROO. The terminating character is CTRL-D. 


COPY #,TEST:MYTEXT.SRC 
The text file MYTEXT.SRC is created on the volume identifier TEST. It 
contains all the data typed in from the keyboard (#CON), until an 
end-of-file character (CTRL-D) is typed. 
ERROR MESSAGES 


SYNTAX ERROR 
ILLEGAL DEVICE NAME 
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ILLEGAL FILE SPECIFICATION 
CANNOT HAVE AMBIGUOUS FILENAME 


FILENAMES MUST BE SAME FORMAT 
ILLEGAL DEVICE FOR COPY PROGRAM 
SOURCE MUST BE TEXT FILE 


END OF MEMORY ADDRESS ERROR 


SOURCE AND DESTINATION ARE THE SAME 


SOURCE FILE IS EMPTY 

ERROR IN VERIFY - FILE NOT COPIED 
FILE SIZES ARE NOT THE SAME 

COMPARE ABORTED AFTER 10 MISMATCHES 


Ambiguous names only accepted in 

a file to file copy 

Ambiguous characters must be in 

the same positions in the 

filenames specified 

Cannot use disk device names 

Only text files can be copied 

to a device 

An error occurred in accessing the 
end of user memory, which is used 
to calculate available buffer 
space. 

the destination file would 
overwrite the source file. This is 
assumed to be a user error since it 
serves no useful purpose. 
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1.2.6 DELAY (RESIDENT) 


The DELAY command causes a task to lose its place in the ready queue and to 
wait for a specified number of time slices. The task will not run during 
this time, even if its priority is higher than other tasks in the system. 
Once the specified number of time slices has passed, the task will resume 
its place in the ready queue. The format of the command is: | 


DELAY taskname[,time slices] 


where 'taskname' is the name of a task currently in the system. The ‘time 
slice’ parameter is optional; its default value is $FFFFFFFF. (This is a 
delay measured in years, effectively "forever.'') The time slice count may 
be any numeric value. ‘The duration of a time slice is normally 50 
milliseconds but shortens with increased I/O activity. Hence, DELAY is 
not reliable as a timing mechanism. The Real-Time Manager should be used 
for applications requiring a truly accurate timer mechanism. (see Part 2 
of the Operating System Reference Manual. ) 


EXAMPLES 


DELAY SYSTEM, 200 (200 time slices) 
DELAY TASK1 ("forever") 


See the RESUME command. 
ERROR MESSAGES 


SYNTAX ERROR 
NO SUCH TASK © 
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1.2.7 DELETE (RESIDENT) 


The DELETE command removes a file from disk. Wildcard characters in 
filenames can be used to remove categories of files. The format of the 
command is: 


DELETE [volume: ]filename.ext 
where ‘volume’ is the disk drive number or the volume identifier. If 
omitted, the default is used. This command will only delete those files 
whose access code indicate they are deletable. (See the SECURE command 


for access code information. The filename and extension fields may 
contain wildcard characters. 


Following a DIR command, the system will "ask" the user to confirm the 
command file by file. A 'Y' response deletes the file. The 'Q' response 
ends the delete prompting. Any other input is interpreted as a NO, and 
the file is not deleted. 
EXAMPLE SEQUENCE 

DELETE 1:TEST? .TXT 

DELETE (Y/N/Q) MYVOL:TEST1.TXT ? N 

DELETE (CY/N/Q) MYVOL: TEST2.TXT ? Y 

DELETE (Y/N/Q) MYVOL:TEST3.TXT ? Y 


drive 1 has three TXT files named TEST1, TEST2, and TEST3. The following 
command sequence removes files TEST2.TXT and TEST3.TXT but not TEST1.TXT. 


ERROR MESSAGES 


SYNTAX ERROR 
FILE NOT FOUND 
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1.2.8 DIAG (RESIDENT) 


The DIAG command invokes the diagnostics of the Computer System. To use 
the diagnostics refer to "PROBLEM ISOLATION MANUAL" (GC22-9192). 
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1.2.9 DIR (RESIDENT/TRANSIENT) 
The DIR command provides a list of the files on a specified volume. The 
format of the command is: 
DIR [[volume:][filename.ext[ ,device]][;options] 

where ‘volume' is the disk drive number or the volume identifier. If 
omitted, the default is used. The 'filename' and 'ext' fields may contain 
wildcard characters. The ‘device’ may be any legal device name except for 
any disk devices. The default device is the page 0 screen (#SCRNO). In 
order to use options with the DIR command, the file DIR.BIN must be on the 
disk in the default drive. The following options are accepted: 

E - extended directory information 

S - alphabetically sorted directory listing 
The directory listing has the following format: 


NAME NAME NAME NAME 


unless the 'E' option is requested. For the 'E' option, the directory has 
the following format: 


NAME TYPE CODE ACCESS CODE LENGTH CREATED REVISED 
The type and access codes are in hexadecimal. The length is the number of 
bytes in the file in decimal. Created and revised are the dates the file 
was created and last revised. 

Note: You can stop the displayed directory from scrolling by pressing 
Ctrl-Numlock. Press any other key to resume. To quit the listing 
press Ctrl-Break. 

EXAMPLES 

DIR 1: 
will list the entire directory of the volume in drive 1. 


DIR 1:*.HEX 


will list on the console all files from drive 1 that have the extension 
HEX. 


DIR TEST? .*,#PR 
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will list on the line printer all files from the default drive that have 
names beginning with TEST followed by a character (or blank). 


ERROR MESSAGES 


SYNTAX ERROR 

FILE NOT FOUND 

DIR.BIN NEEDED ON DEFAULT DRIVE TO PROCESS OPTIONS 
E OPTION NOT SUPPORTED FOR OLD-STRUCTURE DISK 
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1.2.10 DISKCOPY (TRANSIENT) 


The DISKCOPY program copies the contents of the source disk to the 
destination disk. The sectors are copied, starting with logical sector 0, 
and copying through the total number of sectors per disk, including the 
volume identifier. Both source and destination disk must have the same 
physical format, (e.g., sector size and number of sectors per disk). The 
format of the command is: 


DISKCOPY source,destination[ ;options ] 


where source and destination are drive numbers (0-3 correspond to 
#FDOO-#FDO3 and 4-7 correspond to #HDOO-#HDO3), or they may be omitted. 
In this case the user is prompted for source, destination, and desired 
options. Legal options are: 


C -- compare disk. A byte-by-byte comparison is made between the two 
disk devices specified. If a mismatch is found, the format of 
the output is: 


LOGICAL DISK 1 DISK 2 

SECTOR OFFSET BYTE BYTE 

XXXXXXXX XXXX XX XX 

All values printed are in hexadecimal. If ten or more 


mismatches are encountered, an error message is printed and the 
disk comparison is terminated. 


V -- verify destination disk. Sectors are read from the source disk 
and then written to the destination disk. To verify the disk 
copy, the sectors are read back from the destination disk, and 
compared with the original sector data that has been preserved 
in memory. If a mismatch is encountered, an error message is 
printed and the disk copy/verify is terminated. 


R -- recover sector. If a CRC error is found on the source disk, 
whatever data that was read in, is copied to the destination 
disk. This allows the capability to recover partial data from 
bad sectors. The format of the output messages is: 


CRC READ ERROR IN LOGICAL SECTOR $7teeeecrvers 
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DISKCOPY prompts the user, providing a chance to save the contents of the 
destination disk. For example: 


DISKCOPY 
ENTER SOURCE DRIVE NUMBER: 0 
ENTER DESTINATION DRIVE NUMBER: 1 
ENTER OPTIONS: V 
WARNING: DESTINATION DISK CONTENTS 
WILL BE DESTROYED 
COPY FROM DRIVE O TO DRIVE 1 ? Y 
CURRENT DESTINATION VOLUME IDENTIFIER IS: OPSYS 
DO YOU WANT TO CHANGE THE VOLUME IDENTIFIER (Y/N)? Y 
ENTER NEW VOLUME IDENTIFIER: MASTER 
DISKCOPY COMPLETED 


After the disk copy has completed successfully, the user is given the 
opportunity to change the destination disk volume identifier, (this is 
only available for diskette copies). If the volume identifiers of both 
the source and destination diskettes remain the same, a warning message is 
printed indicating that one diskette should be removed. The operating 
system does not support duplicate volume identifiers mounted at the same 
time. 


For a system with only one diskette drive, DISKCOPY prompts the user to 
change from source diskette to destination diskette in the drive 
specified. The program utilizes the maximum amount of user memory space 
available in the system, in order to read and write a multiple number of 
sectors at a time. This enables the user to change diskettes the least 
number of times. 


ERROR MESSAGES 


SYNTAX ERROR 


DISK FORMATS DO NOT MATCH 


END OF MEMORY ADDRESS ERROR 

INVALID DRIVE NUMBER 

CHANGE VOLUME IDENTIFIER ERROR 

VERIFY ERROR: LOGICAL SECTOR *7ive% 
COMPARE ABORTED AFTER 10 MISMATCHES 
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1.2.11 DTCHDEV (RESIDENT) 


The DTCHDEV command detaches a device from an existing driver. The format 
of the command is: 


DTCHDEV device 


where ‘device’ is the device name that is to be detached. 


ERROR MESSAGES 
SYNTAX ERROR 


The device driver may produce unique error messages. See device driver 
documentation. 


Introduction 1-25 


1.2.12 DTCHDRV (RESIDENT) 


The DTCHDRV command detaches a device driver from the operating system. 
The format of the command is: 


DTCHDRV device 


where ‘device’ is the device name of the driver. All control blocks 
associated with the device driver are disabled. 


If the driver supports multiple devices, the devices should be detached 
via the DTCHDEV command before attempting to detach the driver. 


ERROR MESSAGES 


SYNTAX ERROR 


The device driver may one unique error messages. See device driver 
documentation. 
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1.2.13 FORMAT (TRANSIENT) 


The FORMAT program is used to format and initialize a diskette or hard 
disk, so it may be used to store and access files with the Computer System 


operating system. 


FORMAT 


The format of the command is: 


The user is prompted for all required information. A carriage 
return may be entered where default values are specified. 


PROGRAM FUNCTIONS: 


DRIVE NUMBER: 


FORMATS SUPPORTED: 


VOLUME IDENTIFIER: 


INTERLEAVE FACTOR: 


(1) Format and initialize floppy disk. 
(2) Format and initialize 10MB hard disk. 


(3) Change Volume Identifier (floppy disk only). 


(Q) Quit 
Diskette drive numbers are: 0,1,2, or 3 
Hard Disk drive numbers are: 4,5,6, or 7 


10MB Hard Disk, Sector Size 256 

8 inch, Double sided, double density diskette, sector 
size 256 

54-inch, Double sided, double density diskette, sector 
size 256 


Note: The drive type is determined by the 
operating system. 


One to six digits or letters without imbedded blanks; 
e.g., TESTS 


Notes: 1. Prohibited volume names: '0' through '9' 
2. Volume Identifier must be unique, it 
should not already exist on another disk. 


This is used as a fixed value when the physical 
sector numbers are incremented on the disk. The 
disk performance is a function of the interleave 
value. The defaults specified reflect the optimum 
sector interleave. Accepted values are: 


10MB hard disk -- 2 to 32 (default=9) 
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8-inch diskette -- 1 to 13 (default=13) 
5 1/4-inch diskette -- 1 to 8 (default=3) 


BAD SECTOR LIST: (Hard disk only). Each hard disk comes with a list of 
known bad sectors from the manufacturer. These 
logical sector numbers should be entered one at 
atime. They are stored in a bad sector table on 
the hard disk, and are locked out of the sector 
allocation scheme used by the file structure. 


The user will be prompted before the format begins. For a diskette, a ‘Y' 
(yes) or 'N' (no) will be accepted. Since a large amount of data could be 
lost by unintentionally formatting a hard disk, the user must type 'YES' 
twice before the disk will be formatted. 


The FORMAT program executes two passes that are visible to the user. Each 
pass displays the logical sector number being accessed. (To maintain 
readability, the numbers are only displayed after a multiple number of 
sectors have been processed.) The first pass formats all tracks of the 
disk, and initializes sectors with information necessary for the file 
structure. The second pass reads all sectors on the disk as a form of 
verifying the integrity of the disk. If an error occurs in reading a 
sector, a retry is performed. If the read fails again, an error message 
is printed and the process is terminated for diskette formatting. With 
the hard disk, the sector number is put into the bad sector table that is 
stored on disk, and sector verification continues to completion. However, 
if am error occurs in logical sector 0, the disk cannot be used. This 
sector contains descriptive information about the disk, and must be error 
free. 


The file entry 'DIR.DIR' is created in the directory, to be used for file 
access. The time portion of this file indicates when the disk was last 
formatted. | 


ERROR MESSAGES 


OPEN ERROR 

CONFIGURATION ERROR © 

WRITE SECTOR ERROR 

HARD DISK CONTROLLER NOT PRESENT 
DRIVE NOT READY 

RESTORE ERROR 

SEEK TRACK ERROR 

FORMAT TRACK ERROR 

LSN O IS DEFECTIVE 

BAD SECTOR TABLE FULL 

STATUS =S%%wwk Caer = error code in hexadecimal) 


Introduction 1-28 


1.2.14 FREE (TRANSIENT) 


The FREE program displays the status of disk storage (e.g., available, 


used). The format of the command is: 


FREE [drive number] 


where drive number is 0-7. If omitted, the default drive is used. 


EXAMPLES 

FREE 1 

Volume: RAMVOL 

Total Free Sectors: 1967 
Largest Free Contiguous sectors: 1958 
Total Used Sectors: 1881 
Total on Volume Sectors: 3848 


ERROR MESSAGES 


INVALID DRIVE NUMBER 
VOLUME NOT FILE SYSTEM LEVEL 2 
ERROR OPENING . ERROR CODE = 


ERROR READING VOLUME LABEL. ERROR CODE = 


ERROR READING BITMAP. ERROR CODE = 


Bytes: 
Bytes: 
Bytes: 
Bytes: 


503552 
501248 
481536 
985088 


( 51%) 
( 51% 
( 49%) 
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1.2.15 HELP (TRANSIENT) 


The HELP program displays a list of CSOS commands on the console screen. 
The format of the command is: 
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1.2.16 JUMP (RESIDENT) 


The JUMP command allows the user to leave CSOS and go to any arbitrary 
absolute address. This command should be used with care; ANY number will 
be accepted by the command. 
EXAMPLES 

JUMP $E112 
will go to the address E112 (hexadecimal). 


JUMP 256 


will go to the address 256 (decimal). 


ERROR MESSAGES 


BAD PARAMETER 
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1.2.17 KILL (RESIDENT) 


The KILL command removes tasks from the system. The format of the command 
is: 


KILL taskname 


where ‘taskname’ is the name of a task currently in the system (except 
SYSTEM). If the SYSTEM task were to be KILLed, none of the CSOS commands 
described in this manual would be available. 

ERROR MESSAGES 


SYSTEM TASK CANNOT BE KILLED 
NO SUCH TASK. 
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1.2.18 LIST (SUBMIT FILE) 


The LIST command will display an ASCII text file on the screen. This 
command is a submit file that calls the file COPY.BIN from the default 
volume. The format of the command is: 


LIST filename. ext 
where ‘filename.ext' is the name of a text file. If the user has a common 
extension name that he wishes to default to, he could edit the file 
LIST.SUB. For example, the following submit file assumes the extension 


.-oRC for all text files to be listed: 


COPY &0.SRC,#;T 
N 
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1.2.19 LISTDEV (RESIDENT) 


The LISTDEV command lists all devices currently known to the system. 


format of the command is: 


LISTDEV 


If an alternate device identifier is supported (e.g. volume identifier), 
its six-character name is displayed, 


in hexadecimal. 
Device Attributes: 


bit 7 

6 j=driver 
5: l=driver 
4: l=driver 
3: l=driver 
2 Reserved 
1 l=driver 
0 


supports 
Supports 
supports 


supports multiple devices 


along with the device attribute byte 


1=Non sharable device/only 1 outstanding OPEN 
supports 


asynchronous EVENT Posting 
Byte I/O requests 


Asynchronous requests (AREAD, AWRITE) 
Alternate Device ID (Volume Identifier) 


l=driver is reentrant 


Note: Device attributes of hexadecimal 21 is bits 0, 4 and 5 on. 


EXAMPLES 


LISTDEV 
#SCRNO 
ifCON 
#GR 
#SERO2 
#F DOO TEST. 
#FDO3 


21 
30 
Ol 
30 
18 
18 


#SCRN1 
#KPD 
##SEROO 
{#PPU 
#FDO1 


RAM404 


21 


30 
30 
BO 
18 


##CNSLO 
##PR 
#SEROL 
#FDO2 
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21 
BO 
30 
18 


1.2.20 LOAD (RESIDENT) 


The LOAD command transfers a program from disk to the RAM area and prints 
out the transfer address. The program is not executed; control returns to 
CSOS command level. LOAD requires that the file be binary type (00 or 01 
type). The format of the command is: 


LOAD [volume: ]filename.ext 


where ‘volume’ is the disk drive number or the volume identifier. If 
omitted, the default drive is used. No wildcard characters are permitted 
in the filename or extension. If the extension is omitted, the default 
'.BIN' is used. When a program has successfully been loaded, the transfer 
address will be displayed, if file type 01. 


LOAD 1:PROG1 
loads PROG1.BIN from drive 1, into user memory. 
ERROR MESSAGES 
FILE NOT FOUND 
INVALID LOAD FILE FORMAT 


LOAD ADDRESS TOO LOW 
NOT ENOUGH MEMORY FOR LOAD 
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1.2.21 PAGE (RESIDENT) 


The PAGE command switches (toggles) the displayed pages of graphics 
memory. If Page 0 is displayed, then the PAGE command will cause Page 1 to 
be displayed and visa versa. The format of the command is: 


PAGE 
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1.2.22 PRI (RESIDENT) 


The PRI command changes the priority of a task. The format of the command 
is: 


PRI taskname, priority 


where ‘taskname' is the name of a task currently in the system, and 
‘priority’ is the new priority. Priorities can be in the range decimal 1 
to 127. See section on multitasking (section 1.1.5.3) for a description 
of priority. (The SYSTEM tasks priority can be changed, too). 


ERROR MESSAGES 
SYNTAX ERROR 


INVALID PRIORITY 
NO SUCH TASK 
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1.2.23 RAMDIAGS (TRANSIENT) 


The RAMDIAGS program invokes the diagnostics of the Computer System. To 
use the diagnostics refer to PROBLEM ISOLATION MANUAL (GC22-9192). 
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1.2.24 RENAME (RESIDENT) 


The RENAME command changes the name of a file without modifying its 
contents. The format of the command is: 


RENAME [volume: ]oldname.oldext ,newname.newext 
where ‘volume’ is the disk drive number or the volume identifier. If 
omitted, the default drive is used. No wildcard characters are permitted 
in either the new or old names or extensions. The access code of the file 
must be one that allows renaming (see the SECURE command for access-code 
information). Also, newname.newext cannot be the name of a file already 
on the disk. 
EXAMPLES 

RENAME DAVES .OLD, DAVES . NEW 
This renames the file DAVES.OLD to DAVES.NEW. 
ERROR MESSAGES 
DUPLICATE NAME 


SYNTAX ERROR 
FILE PROTECTED 
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1.2.25 REPAIR (TRANSIENT) 


The REPAIR program enables the user to display the contents of a disk 


sector, and edit the data in the sector using a full-screen format. This 
utility will only work on disks formatted under the Release 1.1 Opérating 


System. 


The format of the command is: 


REPAIR 


The following sub-commands may be given: 


+ 


Q 


H 


is the number of a disk sector. If the number is preceded by a 
'$', it is interpreted as a hexadecimal number, otherwise it is 
interpreted as a decimal number. 


NOTE: For information on disk structure, see Appendix E of the 
Operating System Reference Manual, Part 2 (GC22-9200). 


enables the user to edit the sector currently being displayed. 
The cursor moves to the data area. The cursor keys (up, down, 
left, right) may be used to move around the hex and ASCII data 
areas. If changes are made, the corresponding data in a buffer of 
the sector is changed. Pressing Return will update the ASCII area 
to reflect changes made in the hex area, and update the hex area 
to update changes made in the ASCII area. If the user is entering 
data and reaches the end of a hex or ASCII data line, the cursor 
will wrap around to the beginning of the next line of the same 
data type. Pressing the ESC key terminates editing the sector. 
If any changes were made, the user is prompted to update the 
sector on disk or ignore the changes. 


displays the next sector of the disk. 
displays the previous sector of the disk. 
quits program. 


prints the sub-commands available. 


To understand the data fields within a sector that you may wish to observe 
or edit, see Part 2, Appendix E. 
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ERROR MESSAGES 


ERROR OPENING **%%x%* (device name) 

SECTOR NUMBER OUT OF BOUNDS 

ERROR IN READING SECTOR ‘vw 

ERROR IN WRITING SECTOR “evr 

STATUS = $**%" (error code in hexadecimal) 
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1.2.26 RESUME (RESIDENT) 


The RESUME command immediately places a DELAYed task on the ready queue. 
RESUME has no effect on a task already running or on the ready queue. The 
format of the command is: | | 


RESUME taskname 


where ‘taskname' is the name of a task currently in the system. 
ERROR MESSAGES 


NO SUCH TASK 
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1.2.27) RUNTASK (RESIDENT) 


The RUNTASK command starts a task, from the command line. The format of 
the command is: 


RUNTASK filename.ext,priority 


where 'filename.ext' is the name of a binary program that has a transfer 
address (type 01). If no extension is given, the default '.BIN.' is used. 
‘Priority’ is the number indicating the position of the task on the READY 
queue. It can range from 1 to 127. After the task is loaded in memory 
(see Note 1) and has been placed on the READY queue, control returns to 
the system. A maximum of 13 tasks, in addition to the SYSTEM task, is 
allowed. 


ERROR MESSAGES 


SYNTAX ERROR 

INVALID PRIORITY 

NO TRANSFER ADDRESS 

NO MORE TASKS MAY BE STARTED 
DUPLICATE TASK NAME 


The '.BIN' files supplied on the system diskette are not to be executed 
via RUNTASK. They are to be executed from the SYSTEM task by simply 
typing their names: COPY, ASM, FORMAT, BASIC, ... etc. 


NOTES: 


1. Tasks that are to run on the computer simultaneously must be in 
different memory areas to avoid an overlay of programs, and possible 
system crash. 


2. While tasks are being run by RUNTASK, no transient commands 
(e.g. ,FORMAT, COPY) can be executed. These commands load a binary 
file into memory that may overlay a running tasks program. 


3. Programs written in assembler must use the EXIT system call (see 


Operating System Reference Manual Part 2) instead of the RTS 
instruction to exit. 


Introduction 1-43 


1.2.28 SAVE (RESIDENT) 


The SAVE command saves an area of memory as a binary file. The format of 
the command is: 


SAVE [volume: ]filename.ext,startad,endad|,transfer ad] 


where ‘volume’ is the disk drive number or the volume identifier. If 
omitted, the default is used. The filetype of the save file will be 00 if 
no transfer address is present, and 01 if a transfer address is supplied. 
No wildcard characters are permitted in the filename or the extension. If 
the file already exists on the disk, it will be overwritten without 
warning. If the extension specified is .SYS the file created will be 
contiguous rather than the default of extendable. All addresses can be 
entered in decimal or hexadecimal notation. 


EXAMPLES 
SAVE 1:USER.BIN,$9000 ,$97FF, $9100 


this saves 2048 bytes of memory as a binary file to be entered at the 
address 9100 hexadecimal. 


SAVE BASEPAGE.SAV,0,255 


saves the first 256 bytes of memory. 
ERROR MESSAGES 


SYNTAX ERROR 

INVALID FILE SPECIFICATION 

INVALID TRANSFER ADDRESS - the address specified is not on an even 
boundary or it is not between the start and 
end addresses specified. 

ENDING ADDRESS IS TOO LOW OR TOO HIGH - the address specified is below 
the starting address or it is beyond the end 
of system memory. | 
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1.2.29 SECURE (RESIDENT) 


The SECURE command changes a files access code (see below), which 
determines the files security. The code permits protection of certain 
files from change, deletion, or renaming. The format of the command is: 


SECURE [volume: ]filename.ext,access-code 


where the 'volume’ is the disk drive number or the volume identifier. If 
omitted, the default drive is used. No wildcard characters are permitted 
in either the filename or extension. The access codes defined in CSOS 
are: 


not protected 

cannot be deleted 

cannot be renamed 

cannot be deleted or renamed 

is read only (cannot be written) 

is read only and cannot be deleted 

is read only and cannot be renamed 

is read only, cannot be deleted, and cannot 
be renamed. 


SIDE WN F © 


To determine a files current access code, use the DIR command 
with E option. 


EXAMPLES 
SECURE DOS.SYS,0 

removes any Gorse on from the file DOS.SYS on the default drive. 
SECURE INIT.CMD, 2 

protects the file INIT.CMD from being renamed. 
SECURE INIT.CMD,1 

allows INIT.CMD to be renamed but not deleted. 

ERROR MESSAGES 

SYNTAX ERROR 

INVALID FILE SPECIFICATION 


DIR.DIR FILE ACCESS CANNOT BE CHANGED 
VALUE RANGE ERROR 
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1.2.30 SET (RESIDENT) 


The SET command allows the user to control certain system characteristics. 
The format of the command is: 


SET parameter [=value] 


where ‘parameter’ is one of the two-letter mnemonics shown below. If a 


‘value’ is specified, 


the system parameter will be set to it, otherwise 


the current system value will be displayed in decimal. Parameters accept 
values specified as either decimal or hexadecimal. 


DD -- disk drive -- sets or displays the physical drive number to be 


EC -- error code -- 


LD -- line depth os 


LW -- line width ~-- 


SM -- system memory-- 


used as the default when the drive number or volume 
identifier are omitted in a file specification. A 
formatted disk must be mounted in the drive. If 
'DD' is set to drive 0, the default volume 
identifier will always be updated to whatever 
volume is mounted in drive 0. The 'SET DD' command 
accepts a drive number or a volume identifier as 
input, however the default volume is not maintained 
if the disk is moved to another drive. The default 
volume always remains associated with the physical 
drive. 


sets or displays the mode of the status code in 
error messages printed by the system calls PRTERR 
and DPRTERR (see Part 2). If set to 'Y' (Yes), the 
error code will always be printed. If set to 'N' 
(No), the error code is only printed when there is 
no message text. 


sets or displays the number of lines per page for 
the line printer. The default value is 60 lines. 
Accepted values are 1 through 32767. 


sets or displays the number of characters per line 
for the line printer. The default value is 80 
characters. The maximum value is 132. 


sets the amount of memory to be added to (value is 
positive), or removed from (value is negative) the 
system memory pool. After it has been successfully 
set, or if no value is specified, the amount of 
system memory is displayed in 1K byte blocks. (See 
section 1.1.6, System Memory Consumption. ) 
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TS -- tab settings -- sets or displays the tab stops to be used for the 
console. The default value is 10 columns. The 
maximum value is 79. 


EXAMPLES 

SET DD = 2 set default to drive 2, update default volume identifier 
SET DD displays default drive number and volume identifier 

SET EC = Y include error code in error messages 


SET LW = 132 set printer line width to 132 characters 


SET SM 10 increase system memory pool by 10 pages -- (10 x 


1024 bytes) 
ERROR MESSAGES 
SYNTAX ERROR 


BAD PARAMETER 
ILLEGAL VALUE - a nonnumeric or invalid value was entered. 
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1.2.31 SHOW (RESIDENT) 


The SHOW command lists all logical unit numbers and the associated devices 
currently opened for the task specified in the command line. The format 
of the command is: | 
SHOW taskname 

where 'taskname' is the name of a task in the system. The system searches 
the list of open devices for that taskname, and prints out the logical 
unit number and device name for each entry in the list. 
EXAMPLES 
SHOW SYSTEM 

00246 #CON 00249 #SCRNO 00250 #CNSLO 00251 #SCRN1 
shows the opened devices for the system task. 


ERROR MESSAGES 


NO SUCH TASK 
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1.2.32 SPOOL (RESIDENT) 


The SPOOL command invokes the spooler task. If a filename accompanies the 
command, it will be verified, located, and added to the spooler file 
queue. If errors are encountered in the filename or if the file does not 
exist, an error will result. The format of the command is: 


SPOOL [[volume: ]filename.ext] 


where ‘volume’ is the disk drive number or the volume identifier. If 
omitted, the default is used. No wildcard characters are permitted in the 
filename or extension. 


EXAMPLES 
SPOOL SYSVOL: TEXTFILE .TXT 


The printer spooler is a multitasking facility that allows the user to 
retain use of the system while ASCII files are copied to the printer. 
Requests to the spooler are queued on a first come first serve basis. Upon 
receipt of the first request to spool a file, a task is invoked that 
removes files from the spool queue and copies them to the printer. Copying 
proceeds until the queue is exhausted or an error occurs. If an error 
occurs it is logged, and copying is terminated for the file being 
processed. The contents of the queue remain intact following an error and 
the spooling task can be restarted by issuing a SPOOL command. The 
contents of the spool queue may be cleared by using the SPOOLC command 
(see separate listing of this command). Information on the spooler task, 
spooler queue and error log may be obtained by the SPOOLQ command (see 
separate listing of this command). 


Notes: The spooler task runs in operating system space and thus does not 
interfere with user task memory allocation. However, the spooler 
does use operating system resources, and care should be taken to 
avoid conflict with other user activities. Resources used by the 
spooling task include 


#PR Printer (nonshareable device) 
(once the spooler has acquired the printer other tasks may not 
use it until it has been released) 

Disk files at time of submission and copy 
(do not remove disk from drive until all spooled files on the 


disk have been copied to the printer) 


The spooler task currently runs at priority level 100 ($64). 
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1.2.33 SPOOLC (RESIDENT) 


The SPOOLC command ciears the spooler queue of all files but the one 
currently being copied. The format of the command is 


SPOOLC 


For more information on spooler commands, see SPOOL. 
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1.2.34 SPOOLQ (RESIDENT) 
The SPOOLQ command displays status information about the spooling task on 
the console screen. The format of the command is: 
SPOOLQ 
The information displayed includes: 
SPOOLER TASK STATUS (ACTIVE/ INACTIVE) 


SPOOLER ERROR LOG 
SPOOLER FILE QUEUE CONTENTS 


For more information on spooler commands, see SPOOL. 
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1.2.35 SUBMIT (RESIDENT) 


The SUBMIT command allows the use of a file containing CSOS command lines 
as a source of console commands. The text lines in the file are executed 
as though they were typed at the console. SUBMIT can invoke any other 
command under CSOS. The file must be a text file (type 03). The format of 
the command is: 


SUBMIT [volume: ]filename[.ext][,param,...,param] 


where the ‘volume’ is the disk drive number or volume identifier. If 
omitted the default drive is used. All commands from the file will 
attempt to execute regardless of previous command errors. However, a 
submit file can be aborted by pressing Ctrl-Break (the next submit file 
commands will not be executed). 


No wildcard characters are permitted in the filename or extension of the 
SUBMIT file. If the extension is omitted, the default '.SUB' is used. 
All commands from the file will be echoed as they are read. 


SUBMIT files use a special macro indicator, the ampersand symbol (&). 
This macro indicator permits a SUBMIT file to use parameters from the 
SUBMIT command line as it executes. There can be up to 10 parameters in a 
given SUBMIT command line. All parameters must be set off with commas, 
following the first one. Within the SUBMIT file, a parameter is called 
out by the macro indicator and a single decimal digit. Hence, &0 is the 
first parameter and &9 is the tenth parameter. The parameter from that 
position in the command line will be substituted in the SUBMIT file text 
in place of the macro indicator and parameter number. If the parameter 
does not exist, or the parameter number is bad, the parameter value will 
default to a carriage return. A command line, with parameters 
substituted, must be 80 characters or less. 


ERROR MESSAGE 
SYNTAX ERROR 


SUBMIT FILE ERROR 
WRONG FILE TYPE 
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1.2.36 SYSLEVEL (TRANSIENT) 
The SYSLEVEL program displays the release level and version number of the 
operating system. The format of the command is: 
SYSLEVEL 
EXAMPLES 
SYSLEVEL 


RELEASE LEVEL 01 VERSION 01 INTERNAL LEVEL 10 
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1.2.37 SYSMAP (TRANSIENT) 


The SYSMAP program displays the current bounds of available memory on your 
machine. The format of the command is: 


SYSMAP 
e "Start of User Memory" is the lowest address available for you to load 
programs. 
e "End of User Memory" is the highest RAM address available for your 


programs to use. 
e "End of Ram" is the highest RAM address available on your machine. 


e "Total System Memory Pool" is the number of bytes in the system memory 
pool for use by device drivers and the file system. 


: "Total Free Memory" is the current amount of memory from the system 
memory pool that is not in use. 


e "Largest Contiguous Block" is the current largest available 
contiguous block of memory in the system memory pool. 


EXAMPLES 

SYSMAP 

START OF USER MEMORY $00028800 TOTAL SYSTEM MEMORY POOL $00005000 
END OF USER MEMORY SOO11ABFE TOTAL FREE MEMORY | $00004D28 
END OF RAM S$OO011FFFE LARGEST CONTIGUOUS BLOCK $00004D28 
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1.2.38 TASKS (RESIDENT) 


The TASKS command displays the current state of the tasks in the system. 
The format of the command is: 


TASKS 


The tasks are listed in order of their PCB (Process Control Block) number. 
There will be a single line of console output for each task in the system 
(except "idle'"). The task name, priority, time of generation and status 
will be printed. The priority is output in decimal notation. The status 
of a task in the system can be one of the following: 


Ready - task is eligible to run 

Delayed - task is delayed for a certain number of time slices 
Blocked - task is waiting for a device to service an I/O request 
Suspended - task is waiting for completion of asynchronous I[/0 
Terminating - task is undergoing termination 


EXAMPLES 
TASKS 
NAME PRIORITY | CREATE TIME STATUS 
SYSTEM 064 07 NOV 83 01:30:04 READY 
TASK1 010 07 NOV 83 01:44:03 BLOCKED 
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1.2.39 TIME (RESIDENT) 


The TIME command displays or sets the date and current time of day. The 
format of the command is: 


TIME[=dwk dm mon yr hh:mm:ss] 

where 'TIME' alone displays the time, and when followed by parameters, 
sets the time. Time of day is in 24-hour notation. The day of the week 
(dwk) and month (mon) are represented by three-letter abbreviations. The 
other time elements are represented by numbers. If an incorrect syntax or 
an invalid TIME parameter is encountered, the current TIME will be 
printed, along with the appropriate error message. 

The TIME value is preset upon delivery. The system keeps proper elapsed 
time by use of a battery-operated clock. When files are created under 
CSOS, the current time value is stored. 


EXAMPLES 


TIME 
SAT 25 DEC 82 12:00:00 


is the time at noon on Christmas day 1982. 
ERROR MESSAGES 


BAD PARAMETER 
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1.2.40 WHEREIS (TRANSIENT) 
The WHEREIS program displays the load address of a file that has a .BIN 
extension. The format of the command is: 

WHEREIS filename 


Where ‘filename’ is the name of a binary program that has a transfer 
address (type 01). The extension of the file is assumed to be .BIN. 


EXAMPLE 
WHEREIS COPY 


Load address is $OOEO00 
ERROR MESSAGES 


CAN'T OPEN FILE 'filename' .BIN 
CAN'T READ FILE 
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2.0 COMPUTER SYSTEM TEXT EDITOR 


2.1 INTRODUCTION 


ED is a full-screen editor for the IBM Instruments Computer System. It 
enables you to create and edit source and text files. The editing 
features include global and interactive search and replace commands, 
block functions, and a file merging command. 


ED runs on the Computer System with at least 128K of RAM. ED can only edit 
text files created under the Computer System operating system. Files with 
OBJ or BIN extensions cannot be edited. The maximum line length for a 
file line is 133 characters and the maximum number of lines is 1000. 


2.2 GENERAL INFORMATION 


The cursor used by ED is a solid rectangle. It is always displayed in the 
reverse video mode (inverse of normal) from the video mode of the line in 
which it is positioned. 


Marked lines and the command line are displayed in inverse video. All 
other lines are displayed in normal video. 


Commands are entered on the command line and may be executed from the 
command line or from the data area. Functions are assigned to individual 
keys and are executed by pressing the key. Some functions are not 
applicable to the command line, while other functions have different 
effects if executed when the cursor is on the command line or in the data 
area. 


2.3 INVOKING AND EXITING. ED 


You invoke ED by typing ED on the Computer System command line. Once ED 
has been loaded, it issues the prompt “enter a filename or q to quit:". At 
this point, the diskette containing ED can be removed from its drive. 


To edit a file, type in the filename. ED will search for the file. If it 
is found, the first 1000 lines of the file are read into storage and the 
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first 22 lines are displayed. If ED cannot find the file, it assumes that 
a new file is to be created and displays an empty screen. In either case, 
you can now edit the file. 


When you are done editing the file, the File and Quit commands will bring 
back the initial filename prompt. You can edit a new file (or the same 


file again) by entering its name or type "q" or "Q" to exit from ED. 


2.4 STORAGE MANAGEMENT 


Storage is restored before a file is edited. While a file is being 
edited, ED attempts to conserve and reuse storage, but it is possible to 
deplete storage. ED constantly monitors the available storage and issues 
a warning when it is low. At this point you must File or Quit to recover 
storage. Commands and functions that require storage (such as Get) might 
not work or might leave partial results. If you do not File or Quit, ED 
will eventually Quit for you to avoid a heap overflow condition. Any 
changes in the file since the last File or Save will be lost. 


2.5 SCREEN FORMAT 


ED divides the screen into four areas: 
e Data area (lines 1-22) 


ED displays the current window into the file in the data area. Each 
line of the data area displays data from a line of the file. ED uses 
the entire width of the screen (either 40 or 80 characters) for data 
display. | 


If a file line is longer than the screen width, only a segment is 
displayed. Long file lines do not wrap across more than one line in 
the data area. You must move the viewing window to see different 
segments of long file lines. The window may be shifted up, down, 
left, or right by functions described later. 


: Command line (line 23, inverse video) 
You enter ED commands by moving the cursor down to the command line 
(see command toggle function) and typing the command. The editing 


functions described later may be used to edit commands on the command 
line. 
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Status area (lines 24 and 25) 


The status area contains several fields. ED uses the first line of 
the status area to give you information about the file. On this line 
are the filename, the current position in the file, and the current 
value for the insert toggle. 


There are a pair of numbers giving the coordinates of the current 
position in the file. The first number gives the line and the second 
number gives the displacement from the beginning of the line, starting 
at one for the first position of the line. ED indicates the current 
position in the file in another way as well. If the cursor is in the 
data area, it is always at the current position in the current file. 
If the cursor is on the command line, the current position in the file 
is displayed in the reverse video mode of the line that it is in. The 
highlighted character is called the toggle character. 

The possible values for the insert toggle are "Insert" and "Replace." 
The setting of the insert toggle affects what happens when text from 
the keyboard is entered into the data area or the command line of the 
display. 


The second line of the status area is used for messages that ED sends 
to you as a result of commands and functions. This line is also used 
to display internal error codes when ED detects an error in itself. 
To see how internal errors are displayed, invoke the [error] function 
by typing A-E (ALT E). 


2.6 KEYBOARD LAYOUT 


ED attaches special significance to many of the 83 keys on the keyboard. 


The 


names of these keys as referred to in this document and their 


locations on the keyboard are given below. 


Shift keys. The SHIFT, ALT, and CTRL keys together comprise the shift 
keys. The description of a shifted version of a key will be prefixed 
by a one letter code followed by a dash. The possible prefixes are 
"S-" for SHIFT, "A-'" for ALT, and "C-" for CTRL. For example, to 
indicate that the "TAB" key should be depressed while holding down the 
alphabetic shift key, we will say "S-TAB". 


Numeric keypad keys. The keys on the numeric keypad will always be 
used for their control functions, not as numbers. The names of these 
keys (and their numeric labels) are: INS (0), END (1), DOWN (2), PGDN 
(3), LEFT (4), RIGHT (6), HOME (7), UP (8), and PGUP (9). 
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. Delete key. The key to the right of INS is the delete key, written as 
DEL. 


* Return key. The return key is written as RET. 


. Backspace key. The key above RET labeled with a back arrow is the 
backspace key, written as BACKSPACE. 


. Tab key. The key to the left of Q is the tab key, written as TAB. 


. Escape key. The escape key is located above TAB and is written as 
Esc. 


. Function keys. The ten keys along the left edge of the keyboard are 
the function keys. They are referred to as Fl, F2, ..., F10. 


2.4 FUNCTIONS 


Most of the text manipulation that you will do using ED will involve use 
of the functions described in this chapter. Except as noted, functions 
may be used to edit the command line as well as text in the data area of 
the display. 


Functions’ names are lowercase character strings, possibly containing 
blanks, enclosed in square brackets ([]). 


Functions can be divided into several categories, depending on how they 
influence the file and the display. 


Cursor movement functions change only the display; they do not change 
the file being edited in any way. If the action indicated by the 
description of a cursor movement function would make the cursor move off 
the screen, ED will redraw the screen in a function dependent way so that 
the requested position in the file or command line is displayed. No 
function can ever take the cursor outside of the bounds of the file. 
Attempts to do so will move the cursor as far as possible in the requested 
direction. 


Status change functions alter controlling parameters of ED. All of the 
status change functions affect the setting of the insert toggle. | 


File modification functions change the line containing the cursor in some 
way. If you use any of them while the cursor is in the data area of the 
file, the file becomes "dirty," and the Quit command will not allow you to 
discard the contents of the file without confirmation. ED considers the 
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file dirty even if a change is subsequently undone. Changing a command on 
the command line does not cause the current file to become dirty. 


Block functions in ED use the concept of marks and operations on a marked 
block of a file. There can be at most one marked block. A marked block is 
defined by issuing one or two mark line functions. Either the beginning 
or ending mark of a block may be entered first. 


The presence of a marked block does not influence the operation of any 
non-block function or command. In particular, you may add or delete 
characters or lines inside of a marked block. All of the block functions 
in ED operate only on the data area of the display; most of them do nothing 
if invoked while the cursor is on the command line. 
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BACKTAB WORD FUNCTION 


Key: S-TAB 


Purpose: The [backtab word] function moves the cursor to the left, 
stopping at the first character in the previous word. 


A word is defined to be a group of non-blank characters 
separated by blanks. If necessary, ED redraws the display so 


that the new position of the cursor is on the screen. 


see also [tab word]. 
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BEGIN LINE FUNCTION 


Key: HOME 


Purpose: The [begin line] function moves the cursor to the first column 
of the current line. 


If the first column of the current line is not on the display, 
ED redraws the screen or command line so that the first column 
of the line appears in the first column of the screen. If the 
cursor is already in the first column of the current line, 
[begin line] does nothing. 


see also [end line]. 
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BEGIN MARK FUNCTION 


Key: 


Purpose: 


A-1 


The [begin mark] function moves the cursor to the beginning of 
the marked block. 


ED redraws the screen if necessary so that the beginning of the 
marked block is on the display. [begin mark] will not change 
the cursor column; it just jumps vertically to the row 
containing the first line of the marked block, in the same 
column as the cursor or the toggle character (if the cursor was 
on the command line). 


See also [end mark]. 
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BOTTOM FUNCTION 


Key: 


Purpose: 


C-END 


The [bottom] function moves the cursor to the last line of the 
file, without changing its column. 


When [bottom] is invoked, ED redraws the display so that the 
last line of the file is displayed on the last row of the data 


area of the screen. 


If the last line of the file is already on the last row of the 
data area, only the cursor is moved. 


See also [top]. 
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BOTTOM EDGE FUNCTION 


Key: C-PGDN 


Purpose: The [bottom edge] function moves the cursor to the bottom row 
- of the data area. | 


The cursor moves straight down and the contents of the screen do 
not change. 


This function has no effect if the cursor is on the command 
line. 


see also [top edge]. 
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CENTER LINE FUNCTION 


Key: F5 
Purpose: The [center line] function redraws the screen with the line 
containing the cursor at the center line of the screen. 


This 


function has no effect if the cursor is on the command 
line. 
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COMMAND TOGGLE FUNCTION 


Key: ESC 


Purpose: The [command toggle] function swaps the cursor from the data 
area to the command line or vice versa. | | 


If the cursor was on the command line when [command toggle] is 
entered, it moves to the toggle character position in the data 
area. If the cursor was in the data area, it moves to the 
command line and ED highlights its former position in the data 
area by displaying the character in that position in the reverse 
video mode from its current video mode. 


This is the only way to move the cursor onto the command line. 
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CONFIRM CHANGE FUNCTION 


Key: 


Purpose: 


C-BACKSPACE 


The [confirm change] function replaces the target string of an 
interactive Change command with its replacement string. 


This function is only meaningful in the context of an 
interactive Change command. ED will display an error message if 
you try to use it at any time other than immediately after a 


successful interactive Change command. 


See also the Change command in the next chapter. 
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COPY MARK FUNCTION 


Key: A-Z 


Purpose: The [copy mark] function copies a marked block to the position 
given by the cursor. 


ED inserts a copy of the marked lines after the line containing 
the cursor. This function has no effect if the cursor is on the 
command line. 


It is illegal to copy a marked area onto or into itself, and ED 
will not perform the attempted operation: 

ED has no block move function. It may be simulated by a [copy 
mark] followed by a [delete mark]. 


See also [mark line]. 
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DELETE CHAR FUNCTION 


Key: 


Purpose: 


DEL 


The [delete char] function deletes the character at the cursor 
and shifts the remaining characters on the line one position to 
the left to close up the gap. 


You will probably find [delete char] useful mostly for fixing 
errors in existing text. You should use the [rubout] function 
for correcting mistakes immediately after text has. been 


entered. 


see also [insert toggle] and [rubout]. 
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DELETE LINE FUNCTION 


Key: S+F8 


Purpose: The [delete line] function deletes the line containing the 
cursor. | | 


ED shifts the bottom part of the data area up by one line to 
fill in the gap created. The cursor remains stationary. 


This function has no effect if the cursor is on the command 
line. | : , 


See also [insert line]. 
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DELETE MARK FUNCTION 


Key: A-D 
Purpose: The [delete mark] function deletes the lines in the marked 
block and unmarks the file. ED redraws the screen and relocates 


the cursor if part of the block was displayed. 


See also [unmark] and [mark line]. 
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DOWN FUNCTION 


Key: 


Purpose: 


DOWN 


The [down] function moves the cursor one position towards the 
bottom of the screen, without changing its column. 


If you invoke [down] when the cursor is positioned on the last 
line of the data area, ED scrolls the screen up by one line, 
bringing a new line into view. 


When the cursor is on the command line, [down] has a slightly 
different meaning. In this context, [down] scrolls the display 
up by one line, then moves the cursor to the new line of data 
uncovered. You must use the [command toggle] function to return 
the cursor to the command line. 


If the cursor is already on the last line of the file when 
[down] is invoked, nothing happens. 


See also [up] and [down4]. 
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DOWN4 FUNCTION 


Key: 


Purpose: 


F2 


The [down4] function moves the cursor four positions towards 
the bottom of the screen, redrawing the screen if necessary. 


If [down4] is invoked when the cursor is positioned in the 
bottom three lines of the data area of the screen or on the 
command line, ED moves the cursor to the bottom line of the data 
area and redraws the data so that the line number of the bottom 
line in the data area is four greater than the previous contents 
of that screen line. If the cursor is within three lines of the 
bottom of the file when [down4] is invoked, ED moves the cursor 
to the bottom line of the file, redrawing the screen as 
necessary. 


See also [up4] and [down]. 
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END LINE FUNCTION 


Key: END 


Purpose: The [end line] function moves the cursor to the end of the 


line. 


If the last column of the current line is not on the display, ED 
redraws the file or command line so that the last column of the 
line is shown in approximately the middle of the screen. If the 
cursor is already at the end of the current line, [end line] 


does nothing. 


Since the cursor may be past the end of the line when [end line] 
is invoked, it is possible that [end line] will move the cursor 


to the left. 


See also [begin line]. 
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END MARK FUNCTION 


Key: 


Purpose: 


A-2 


The [end mark] function moves the cursor to the end of the 
marked block. 


ED redraws the screen if necessary so that the end of the marked 
block is on the display. [end mark] does not change the cursor 
column; it just jumps vertically to the row containing the last 
line of the marked block in the same column as the cursor or 
toggle character (if the cursor was on the command line). 


See also [begin mark]. 
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ERASE END LINE FUNCTION 


Key: F6 


Purpose: The [erase end line] function erases characters rightward from 
the cursor to the end of the line. 


The new length of the line will be one less than the column 
number of the cursor. 


The cursor does not move. 
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ERROR FUNCTION 


Key: 


Purpose: 


A-E 


The [error] function gives an example of the message ED 
produces when it detects an error in its own code. 


If you get such an internal error message while you are using 
ED, try scrolling to a different page and then back to the point 
of the error, then retry the operation which caused the error 
message. If the problem persists, try to figure out the 
sequence of steps that is required to force ED to fail, then 
send a documented description of the error circumstances to IBM 
Instruments. 
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EXECUTE FUNCTION 


Key: C-RET 

Purpose: The [execute] function performs the command on the command 
line, even if the cursor is not currently on the command line. 
The RET key always performs the [execute] function when the 
cursor is on the command line. The [execute] function is very 
useful in conjunction with the Change and Locate commands, to 
repeat the previous operation. 
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INSERT LINE FUNCTION 


Key: F9 


Purpose: The [insert line] function adds a new line to the current file 
following the line containing the cursor. 


ED positions the cursor in the first column of the new line and 
shifts lines following the new line down to make room for the 
new line. 

The only way to insert a line before the beginning of the file 
is to perform [split] when the cursor is positioned on the first 


character of the file. 


This function has no effect if the cursor is on the command 
line. 


See also [delete line] and [return]. 
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INSERT TOGGLE FUNCTION 


Key: 


Purpose: 


INS 


The [insert toggle] function changes the setting of the insert 
toggle from Insert mode to Replace mode, or vice versa. 


ED displays the current setting of the insert toggle as a field 
in the status area. The possible values for the insert toggle 
setting in the status area are 'Insert' and 'Replace’. 


If the insert toggle is set to ‘Replace,’ the character you type 
replaces the character at the current cursor position, no other 
characters of the line are affected, and ED moves the cursor one 
position to the right. 


If the insert toggle is set to ‘Insert,’ ED shifts the 
characters of the current line from the cursor to the end of the 
line right by one position, places the new character in the 


space this created at the cursor position, and moves the cursor 


one position to the right. Characters at the right edge of the 
screen are shifted off the screen. 


Note: if the line containing the cursor is 133 characters long 
(maximum length), inserting a character will cause the last 
character in the line to be deleted. 


The [return] function is also affected by the insert toggle. 


See also [return]. 
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JOIN FUNCTION 


Key: A-J 


Purpose: The [join] function appends the successor of the line 
containing the cursor to the cursor line. 


The cursor may be located anywhere in the data area and does not 
move after you perform [join]. ED redraws the data area of the 
screen after [join] to close up the gap created when the next 
line is moved up onto the cursor line. 


Tf you execute [join] immediately after [split], the display 
will not change. 


If the combined length of the cursor line and its successor line 
is greater than 133 (maximum line length), [join] is not done. 


This could be due to blanks at the end of the lines. 


This function has no effect if the cursor is on the command line 
or is on the last line of the file. 


See also [split]. 
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LEFT FUNCTION 


Key: LEFT 

Purpose: The [left] function moves the cursor one position to the left. 
If the requested move would cause the cursor to move off the 
screen, ED redraws the display so that the new cursor position 
and some surrounding context appear on the screen. If the 


cursor is already in column one, [left] has no effect. 


See also [right], [left8], and [left40]. 
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LEFT8 FUNCTION 


Key: F3 


Purpose: The [left8] function moves the cursor eight positions to the 
left. 


This function allows faster horizontal scrolling than the 
[left] function. 


If the requested move would cause the cursor to move off the 
screen, ED redraws the display so that the new cursor position 
and some surrounding context appear on the screen. If the 
cursor is already in the first seven columns of the line, 


[left8] moves the cursor to column 1. 


See also [right8] and [left]. 
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LEFT40 FUNCTION 


Key: C-LEFT 


Purpose: The [left40] function moves the cursor forty positions to the 
left. 


This function allows faster horizontal scrolling than the 
[left] and [left8] functions. 


If the requested move would cause the cursor to move off the 
screen, ED redraws the display so that the new cursor position 
and some surrounding context appear on the screen. If the 
cursor is already in the first forty columns of the line, 
[left40] moves the cursor to column 1. 


See also [right40], [left8], and [left]. 
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MARK LINE FUNCTION 


Key: 


Purpose: 


A-L 


The [mark line] function sets a mark on the line containing the 
cursor. 


If there are no marks in the file, ED redisplays the current 
line in inverse video. If this is the second line mark in the 
file, ED displays the cursor line and all lines between it and 
the other marked line in inverse video. One or more marked 
lines forms a marked block. 


The cursor must be in the data area when you invoke [mark line]. 


It is an error to invoke [mark line] if there are already two 
marks outstanding. 


The highlighting associated with line marks always spans an 
entire row of the screen. Thus, even though a line may be only 
10 characters long, if the line is part of a block, ED will 
highlight the entire screen row used to display the line. 


Blocks can be used to copy, delete, shift, and save sections of 
a file. 


See also [unmark], [delete mark], [copy mark], [shift right], 
[shift left], and the Save command in the next section. 


Computer System Text Editor 2-31 


PAGE DOWN FUNCTION 


Key: 


Purpose: 


PGDN 


The [page down] function scrolls the display down to the next 
page. 


ED redraws the display so that the 20 lines below the current 
screen contents (higher line numbers) are brought into view. If 
there are less than 20 lines below the line currently on the 
bottom row of the data area, ED displays the last 22 lines of 
the file. 


The cursor is normally not moved by [page down]. This implies 
that the sequence [page down] followed by [page up] usually 


leaves the cursor in its original position. 


See also [page up]. 
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PAGE UP FUNCTION 


Key: 


Purpose: 


PGUP 


The [page up] function scrolls the display up to the previous 
page. 


ED redraws the display so that the 20 lines above the current 
screen contents (lower line numbers) are brought into view. If 
there are less than 20 lines above the line currently on the top 
row of the data area, then ED displays the first 22 lines of the 
file. 


The cursor is normally not moved by [page up]. This implies 
that the sequence [page up] followed by [page down] usually 


leaves the cursor in its original position. 


See also [page down]. 
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RETURN FUNCTION 


Key: 


Purpose: 


RET. 


The [return] function executes a command if the cursor is on 
the command line and positions the cursor on the next line if 
the cursor is in the data area. 


When the cursor is on the command line, [return] causes ED to 
interpret and perform the command on the command line. If the 
command is invalid, the cursor will not move; otherwise the 
effect depends upon the command. See the command section for 
information on specific commands. 


When the cursor is in the data area, the effect of [return] 
depends - upon the insert toggle. In ‘Replace’ mode, [return] 
sets the cursor in column one of the line after the cursor line. 
ED will redraw the screen if this line or column is not on the 
screen. In "Insert" mode, [return] has the following result: a 
new line is inserted into the file after the cursor line and the 
cursor is moved under the first non-blank character in the 
cursor line. 
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RIGHT FUNCTION 


Key: RIGHT 


Purpose: The [right] function moves the cursor one position to the 
right. 


If the requested move would cause the cursor to move off the 
screen, ED redraws the display so that the new cursor position 
and some surrounding context appear on the screen. If the 


cursor is already in column 133, [right] has no effect. 


see also [left] and [right8]. 
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RIGHT8 FUNCTION 


Key: 


Purpose: 


F4 


The [right8] function moves the cursor eight positions to the 
right. 


This function allows faster horizontal scrolling than the 
[right] function. 


If the requested move would cause the cursor to move off the 
screen, ED redraws the display so that the new cursor position 
and some surrounding context appear on the screen. If the 
cursor is near the maximum length of a line (columns 125 through 
133) [right8] moves the cursor to column 133, the maximum 
allowable column. 


see also [left8] and [right]. 
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RIGHT40 FUNCTION 


Key: 


Purpose: 


C-RIGHT 


The [right40] function moves the cursor forty positions to the 
right. 


This function allows faster horizontal scrolling than the 
[right] and [right8] functions. 


If the requested move would cause the cursor to move off the 
screen, ED redraws the display so that the new cursor position 
and some surrounding context appear on the screen. If the 
cursor is near the maximum length of a line (columns 93 through 
133) [right40] moves the cursor to column 133, the maximum 
allowable column. 


See also [left40], [right8], and [right]. 
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-RUBOUT FUNCTION 


Key: BACKS PACE 


Purpose: The [rubout] function deletes the character to the left of the 
cursor and shifts the remaining characters on the current line 
one position to the left to close up the gap. 


If the cursor is in column one, [rubout] will delete the first 
character on the line and shift the remaining characters left by 
one position. 

You will probably find [rubout] useful mainly for correcting 
mistakes immediately after they have been typed. You should use 


the [delete char] function for correcting existing data. 


See also [insert toggle] character and [delete char]. 
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SHIFT LEFT FUNCTION 


Key: 


Purpose: 


F7 


The [shift left] function shifts the text in a marked block to 
the left. 


ED writes the prompt "shift left - how many columns ? (0-133)". 
When you respond with the size of the shift, ED deletes that 
many characters from the beginning of each line in the marked 


block. 


This function has no effect if the cursor is on the command 
line. 


see also [shift right]. 
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SHIFT RIGHT FUNCTION 


Key: F8 


Purpose: The [shift right] function shifts the text in a marked block to 
the right. 


ED writes the prompt "shift right - how many columns? (0-133)". 
When you respond with the size of the shift, ED inserts that 
many blanks into each line of the marked block before the first 
character on the line. 


This function is most useful for indenting program text. 


Note that characters shifted past column 133 (maximum line 
length) will be deleted. 


This function has no effect if the cursor is on the command 
line. 


See also [shift left]. 
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SPLIT FUNCTION 


Key: 


Purpose: 


A-S 


The [split] function divides the line containing the cursor at 
the cursor. 


ED moves text at or following the cursor on the current line to 
the beginning of a new line which ED inserts into the file 
following the cursor line. The cursor does not move. 


This function has no effect if the cursor is on the command 
line. 


The only way to insert a line before the beginning of the file 
is to perform [split] when the cursor is positioned on the first 
character of the file. 


see also | join]. 
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TAB WORD FUNCTION 


Key: TAB 


Purpose: The [tab word] function moves the cursor to the right, stopping 
at the first character in the next word. 


A word is defined to be a group of non-blank characters 
separated by blanks. If the cursor is at or beyond the end of 
the line, [tab word] does not move the cursor. If necessary, ED 
redraws the display so that the new position of the cursor is on 
the screen. 


see also [backtab word]. 
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TOP FUNCTION 


key: C-HOME 


Purpose: The [top] function moves the cursor to the first line of the 
file, without changing its column. 


When [top] is invoked, ED redraws the display so that the first 
line of the file is displayed on the first row of the data area 


of the screen. 


If the first line of the file is already on the first row of the 
data area, only the cursor is moved. 


see also [bottom]. 
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TOP EDGE FUNCTION 


Key: C-PGUP 


Purpose: The [top edge] function moves the cursor to the top row of the 
| data area. 


The cursor moves straight up and the contents of the screen do 
not change. 


This function has no effect if the cursor is on the command 
line. 


See also [bottom edge]. 
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UNMARK FUNCTION 


Key: 


Purpose: 


A-U 
The [unmark] function removes any existing marks. 


The text inside of the marked block is not affected by [unmark]. 


If a marked block was on the screen, 


ED removes the inverse 
video highlighting of the area. 


You may execute [unmark] no matter where the cursor is located. 


see also [mark line]. 
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UP FUNCTION 


Key: 


Purpose: 


UP 


The [up] function moves the cursor one position towards the top 
of the screen. 


Invoking [up] when the cursor is positioned at the top of the 
screen causes the cursor to remain stationary and the data on 
the screen to shift down by one line, bringing a new line into 
view. If the cursor is already at the top of the file when [up] 
is invoked, nothing happens. , 


If the cursor is on the command line when you invoke [up], it 
moves to the bottom line of the data area. You must use the 
[command toggle] function to return the cursor to the command 
line. 


see also [down] and [up4]. 
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UP4 FUNCTION 


Key: 


Purpose: 


F1 


The [up4] function moves the cursor four positions towards the 
top of the screen, redrawing the screen if necessary. 


If [up4] is invoked when the cursor is positioned in the top 
three lines of the data area of the screen, ED moves the cursor 
to the top line of the data area and redraws the data on the 
display so that the line number of the top line in the data area 
is four less than the previous contents of that line. If the 
cursor is within three lines of the top of the file when [up4] 
is invoked, ED moves the cursor to the top line of the file, 
redrawing the screen as necessary. 


see also [down4] and [up]. 


Computer System Text Editor 2-47 


2.8 COMMAND REFERENCE 


Commands are entered on the command line and may be up to 133 characters 
long. The first character of the command can be preceded by any number of 
blanks. Commands can be entered in upper or lower case. One or.more 
blanks are required to separate the name of a command from any argument, 
except for the Change and Locate commands. 


In all commands, extraneous information at the end of a command line is 
ignored. | 


In the command reference section that follows, the ED commands appear 
alphabetically. The description of each command includes its name, its 
format, a short description, then a more detailed description explaining 
the operation of the command and its optional parameters, as well as 
references to related commands. 


In contrast to the function reference section of the last chapter, square 


brackets ([]) are used in this section to indicate optional arguments to 
commands. 
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CHANGE COMMAND 


Format: 


Purpose: 


C /pattern/newstring/[-][*] 


The Change command changes occurrences of a pattern string to a 
replacement string, either one occurrence at a_e time 
interactively or globally, starting next to the cursor position 
or the toggle character (if the cursor is on the command line). 


For a global change, use the star (*) at the end of the command. 
Interactive change commands do not end with star. Global 
changes alter every occurrence of the target string. 
Interactive changes are more complicated. 


When ED performs an interactive Change command, it locates the 
next occurrence of the target string and moves the cursor to it, 
but does not yet make the change. To actually change the target 
string to the replacement string, you must use the [confirm 
change] function (C-BACKSPACE). If you do not wish to change 
the particular occurrence of the target string that was found, 
just enter anything other than [confirm change]. 


The interactive Change command remains on the command line 
after it is executed, so that you may perform an [execute] 
function (C-RET) to retry the Change command and locate the next 
occurrence of the target string. 


The character used to separate the pattern and replacement 
strings is the first non-blank one after the command name, as 
for the Locate command. You must enter all three occurrences of 
this delimiter. 


The search always starts in the column next to the cursor 
position or toggle character. The optional minus sign in the 
Change command controls the direction of the search. If it is 
absent, the search direction is forward (towards higher 
numbered lines), while if the minus sign is present the search 
works backwards towards the top of the file. 


ED ignores the case of the pattern and of the text in the file 
when searching. Thus, the pattern /MiXeD/ will find any of the 
strings "mixed", "MIXED", or "“mIxEd". ED preserves the case of 
characters in the replacement string. 


Note: If the first non-blank character on the command line is a 
q 


'C' or a ‘'c', ED will attempt to perform a change. Anything 
after the command is ignored. 
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Each entry in the following table is a legal Change command: 


Gn ee 


| Command | Comments | 
| c/xyz/abc/ | Changes "xyz" to "abc" | 

| interactively with a forward | 
| | search. | | 


caxyzaa*1? | Deletes all occurrences of | 
| "xyz" (by changing them to | 
| the empty string) from the | 
| current file position to the | 
| end of the file. 1? is | 
| ignored. | 
C/xyz/XYZ/-* | Capitalizes all occurrences | 
| of "xyz" between the | 
| beginning of the file and | 
| the current position in the | 
| file. | 


| Changes all occurrences of | 
| "/*" that occur between the | 
| current position in the | | 
| file and the end of the | 
| file to "(*", | 


See also the Locate command. 
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FILE COMMAND 


Format: File 


Purpose: The File command writes a copy of the current file to disk 
using the name in the status area and removes it from memory. 


See also the Name and Save commands. 
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GET COMMAND 


Format: Get filename [(L1,L2)] 


Purpose: The Get command copies part or all of another file into the 
file being edited. ED searches for the file with the specified 
filename. If the file is found, ED inserts it after the line 
containing the cursor or the toggle character (if the cursor is 

on the command line). 


To get only part of a file, use the (Ll, L2) option, replacing 
Ll with the line number of the first line to be copied and L2 
with the line number of the last line to be copied. 


If the specified file (or the requested part of it) is too long 
to fit into the file being edited, none of the file is inserted. 
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LOCATE COMMAND 


Format: 


Purpose: 


[L] /pattern[/[-]] 


The Locate command finds the next (or previous) occurrence of a 
pattern string in the current file, starting next to the cursor 
position or the toggle character (if the cursor is on the 
command line). 


ED searches for the specified pattern and moves the cursor to 
the first place it is found, redrawing the display if necessary. 
The Locate command remains on the command line after it is 
executed, so that the [execute] function (C-RET) may be used to 
repeat the search without retyping the command. 


You need to specify the name of the Locate command only if the 
search pattern contains the slash character (/). In this case, 
you must use some character other than slash to delimit the 
pattern. ED takes the first non-blank character after the 
command name to be the pattern delimiter. The second occurrence 
of this character terminates the pattern. The closing 
delimiter is optional unless the minus sign is specified or L is 
specified. 


The search starts in the column next to the cursor position or 
toggle character. The optional minus sign in the Locate command 
controls the direction of the search. If it is absent, the 
search direction is forward (towards higher numbered lines), 
while if the minus sign is present the search works backwards 
towards the top of the file. 


ED ignores the case of the pattern and of the text in the file 
when performing the search. Thus, the pattern /MiXeD/ will find 
any of the strings "mixed", "MIXED", or "mIxEd". 


Note: If the first non-blank character on the command line is 
an 'L', '1l', or '/' ED will attempt to do a locate. Anything 
after the locate command is ignored if the command begins with 
'L', else it could be part of the pattern. 
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Each entry in the following table is a legal Locate command: 


Bis eee ee ger See ea Be ee ee 


| Command 


Comments | 


| | | an ae ane ve nee 


| /xyz 


| /xy2/- 

| Lixyz' 

| L2/*2 

| /xyz abc/ 
| L-xyz-- 


| L, '9', abc 
| 
| / '9' abc 


Searches forward for "xyz" | 
(assuming z is the end of the line) | 


Searches backward for "xyz". | 
Searches forward for "xyz". | 
Searches forward for "/*". | 
Searches forward for "xyz abc". | 
Searches backward for "xyz". | 


Searches forward for " '9'", | 
ignoring abc | 


Searches forward for " '9' abc" (and | 
anything else after abc) | 


See also the Change command. 
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NAME COMMAND 


Format: 


Purpose: 


Name filename 


The NAME command assigns a new name to a file; that is, it saves 
an existing file under a new name. The "old" file is not lost, 
however, and can be retrieved under its original name. ED 
changes the filename given in the status area. 


ED does no checking of the specified filename. If an invalid 
filename is assigned to a file with the Name command, the error 
will not be detected until an attempt is made to write out the 
file. 


The Name command sets the indicator that records that the file 
has been changed. 


See also the File and Save commands. 
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QUIT COMMAND 


Format: Quit 


Purpose: The Quit command terminates editing of a file and removes it 
from memory without writing it to disk. 


If you have modified the file or changed its name since the last 
time it was saved to disk, ED writes the prompt "The file has 
been modified. Do you want to quit? (y/n)" in the status area. 


To confirm the quit, type "y" or "Y". To abort the quit, type 


mn" Or ia alae 


If the file had not been modified, or after quit confirmation, 


ED destroys the copy of the file in memory and redraws the 
display to prompt for another file to edit. 
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SAVE COMMAND 


Format: 


Purpose: 


Save [filename] [{ (block) ] 
The Save command writes a copy of the file to disk. 


If you do not specify a filename, the Save command writes out 
the file to disk using the name in the status area. If you do 
give a filename, the file is written using that name. In either 
case, the file is not removed from memory. 


If you specify the (block) option, the Save command writes out 
the lines in the current marked block (if there is one). The 


(block) option cannot be specified without a filename. 


To obtain a printed listing of the block or file, you may "Save" 
it to the file #pr as: 


save #pr [ (block) ] 
The file modification indicator is not reset by the Save command 
unless Save is entered without a filename and without the 
(block) option. This is to prevent a later Quit command from 
releasing a file that has been "Saved" only to the printer or 
only partially saved. 


See also the File and Name commands. 


You should not save a file to the current screen (#SCRNO). 
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The following table lists all of the functions of ED, their default keys, 
and whether they can be invoked from the data area, command line, or both. 


|Function name | neds invoked | Default key | 
| backtab word | De | S-TAB | 
| begin line «4 Pane | HOME | | 
a 
| begin mark | oD, Cc | A-1 | 
| bottom | “Dect | C-END | 
ice peetathe amr endiseenta ston lcci) acceler Semaine 
| bottom edge | oD | C-PGDN | 
| oacareectsias 
| command toggle i Ds | ESC | 
| confirm change | D | C-BACKSPACE | 
| fen | | 
| copy mark | D | A-Z | 
| delete’ char . fb. Dye | DEL | 
SS SS SSS SSS SS SS ee 
| delete line | D | S-F8 | 
bere ceceesiyiimerneain benoit ems 
| delete mark br Dy. | A-D | 
| down | | D, Cc | DOWN | 
— SS uaa ase 
| down4 | | r Det | F2 | 
caer aco ose mraneraresaiaenimisieaniehad 
| end line | Dei | END | 
_————__+—___+ 
| end mark (| 2-6 | A-2 : | 


Se errr on ena eC AO Ne EE AY ev eee ee) Leet ee rere cee ran 


D - can be invoked from data area 
C - can be invoked from the command line 
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ay ee Pe es oe ee rc i ee WM ge a er ey 


| erase end line | oD, Cc | F6 | 
eninge 
| error | D, C | A-E | 
nn ernnen Someenniarnnene Sian anne 
| execute i 2De. 20 | C-RET | 
ens aes Sn 
| insert line ~ “D | F9 | 
pecan sce erinntnide Leeman aed 
| insert toggle a) ee | INS (F10*) | 
—__.-____--_-_} —___ ——-- +} —____-__. 
| join | oD | A-J | 
renee een nos ORE 
| left | oD, Cc | LEFT | 
eens eae 
| left8 / oD, c¢ | F3 | 
Se 
| left40 De | C-LEFT | 
nee eee nenene nen 
| mark line | OD | A-L | 
soiree reenter enmenintioottee 
| page down | D, Cc | PGDN | 
eee Coane 
| page up fF eG | PGUP | 
pe oreo peel nermmtiisnl 
| return | D.C | RET | 
| right | Dd, Cc | RIGHT | 
ann eee nee 
| right8 r DC | F4 | 
a ee ne 
| right40 | 1 pe | C-RIGHT | 
arenes eee aes 
| rubout | D.C | BACKSPACE | 
oe serreescirmarasnseeensgrecroetonert accrinecsene 
| shift left | F7 | 
i oo 
| shift right | | F8 | 


pee ee 
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Ca a aa aT a aS ea 
| split | OD | A-S | 
i oo 


| tab word | D, Cc | TAB | 
| top | oD, Cc | C-HOME | 


| top edge | OD | C-PGUP | 
6:2 cc 


| unmark | D, Cc | A-U | 
| up | D, Cc | UP | 


| up4 | oD, © | Fl | 
a eT 


Commands: 


C /pattern/newstring/{-][]*] 
File 

Get filename [(L1,L2)] 

L /pattern/[-|] 

Name filename 

Quit 

Save [filename] [ (block) ] 
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3.0 COMPUTER SYSTEM MACRO ASSEMBLER 


3.1 SCOPE 


The intent of this chapter is to provide sufficient information to develop 
68000 assembly language programs which may be run on the Computer System. 
The information herein pertains to the elements of the assembler. 
Detailed information pertaining to the 68000 microprocessor is provided 
in various generally available publications. 


3.1.1 INTRODUCTION 


The Computer System Assembler is used to translate assembler source 
programs into a relocatable form suitable for further processing with the 
linker, ALINK. The assembler runs on the IBM Instruments Computer System 
Operating System. 

The assembler includes the following features: 

e Relocatable code generation 


: Complex expressions 


° Symbol table listing 


af Macros 

e Conditional assembly 
° Structured syntax 

e Cross-reference 


3.1.2 ASSEMBLY LANGUAGE 


The symbolic language used to code source programs for processing by the 
assembler is called 68000 assembly language. This language is composed of 
the following symbolic elements: 
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a. Symbolic names or labels, which represent instruction, 
directive, and register mnemonics, as well as user-defined 
memory labels and macros. 


b. Numbers, which may be represented in binary, octal, decimal, or 
hexadecimal notation. 


c. Arithmetic and logical operators, which are employed in complex 
expressions. 


d. Special-purpose characters, which are used to denote certain 
operand syntax rules, macro functions, source line fields, and 
numeric bases. 


3.1.2.1 Machine-Instruction Operation Codes 


Appendix B summarizes that part of the assembly language that provides 
mnemonic machine-instruction operation codes for the 68000 machine 
instructions. 


3.1.2.2 Directives 


The assembly language contains mnemonic directives which specify 
auxiliary actions to be performed by the assembler. Directives are not 
always translated to machine language. 


Assembler directives assist the programmer in controlling the assembler 
output, in defining data and symbols, and in allocating storage. 


3.1.3 68000 ASSEMBLER 


The assembler translates source statements written in the 68000 assembly 
language into relocatable object code, assigns storage locations to 
instructions and data, and performs auxiliary assembler actions 
designated by the programmer. Object modules produced by the assembler 
are compatible with the Computer System linker ALINK, referred to as the 
"linkage editor’ or "linker." 


The assembler includes macro and conditional assembly capabilities, and 
implements certain "structured" programming control constructs. The 
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assembler generates relocatable code which may then be linked into a 
memory image format. 


3.1.3.1 Assembler Purposes 


The two basic purposes of the assembler are to: 


. Provide the programmer with the means to translate source statements 
into relocatable object code -- that is, to the format required by the 
linker. 


: Provide a printed listing containing the source language input, 
assembler object code, and additional information (such as error 
codes, if any) useful to the programmer. 


3.1.3.2 Assembler Processing 


Assembly is a two-pass process. During the first pass, the assembler 
develops a symbol table, associating user-defined labels with values and 
addresses. During the second pass, the translation from source language 
to machine language takes place, using the symbol table developed during 
pass 1. In pass 2, as each source line is processed in turn, the assembler 
generates appropriate object code and the assembly listing. 


3.1.4. RELOCATION AND LINKAGE 


"Relocation refers to the process of binding a program to a set of memory 
locations at a time other than during the assembly process. For example, 
if subroutine "ABC" is to be used by many different programs, it is 
desirable to allow the subroutine to reside in any area of memory. ABC is 
assembled once, producing an object module which contains enough 
information so that another program (the linker) can easily assign a new 
set of memory locations to the module. 


In addition to program relocation, the linkage editor must also resolve 
inter-program references. For example, the other programs that are to use 
subroutine ABC must contain a jump-to-subroutine instruction to ABC. 
However, since ABC is not assembled at the same time as the calling 
program, the assembler cannot put the address of the subroutine into the 
operand field of the subroutine call. The linkage editor, however, will 
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know where the calling program resides and, therefore, can resolve the 
reference to the call to ABC. This process of resolving inter-program 
references is called "linking." An example of linking two object modules 
is shown in Appendix E. 


3.1.5 NOTATION 


Commands and other input/output (1/0) are presented in this manual in a 
modified Backus-Naur Form (BNF) syntax. Certain symbols in the syntax, 
where noted, are used in the real I/0; however, others are meta-symbols 
whose usage is restricted to the syntactic structure. These meta-symbols 
and their meanings are as follows: 


< > The angular brackets enclose a symbol, known as a syntactic 
variable, that is replaced in a command line by one of a 
class of symbols it represents. 


This symbol indicates that a choice is to be made. One of 
several symbols, separated by this symbol, should be 
selected. 


[ ] Square brackets enclose a symbol that is optional. The 
enclosed symbol may occur zero or one time. 


ic args Square brackets followed by periods enclose a symbol that 
is optional/repetitive. The symbol may appear zero or more 
times. 


Operator entries are to be followed by a carriage return. 


3.2 SOURCE PROGRAM CODING 


3.2.1 INTRODUCTION 


A source program is a sequence of source statements arranged in a logical 
way to perform a predetermined task. Each source statement occupies a 
line of printable text, where each line may be one of the following: 


a. Comment 


b. Executable instruction 
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c. Assembler directive 


d. Macro invocation 


3.2.2 COMMENTS 


Comments are strings, composed of any ASCII characters (refer to Appendix 
C), which are inserted into a program to identify or clarify the 
individual statements or program flow. Comments are included in the 
assembly listing but, otherwise, are ignored by the assembler. 


A comment may be inserted in one of two ways: 
1. At the beginning of a line, starting in column one, where an asterisk 
(*) is the first character in the line. The entire line is a 


comment, and an instruction or directive would not be recognized. 


2. Following the operation and operand fields of an assembler 
instruction or directive, where it is preceded by at least one space. 


EXAMPLES: 
* THIS ENTIRE LINE IS A COMMENT. 


BRA LAB2 THIS COMMENT FOLLOWS AN INSTRUCTION. 


Sy EXECUTABLE INSTRUCTION FORMAT 


68000 assembly language programs are translated by the assembler into 
relocatable object code. This object code may contain executable 
instructions, data structures, and relocation information. This 
translation process begins with symbolic assembly language source code, 
which employs reserved mnemonics, special symbols, and user-defined 
labels. 68000 assembly language is line-oriented. 


3.2.3.1 Source Line Format 


Each source statement has an overall format that is some combination of 
the following four fields: 
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1. label 

2. operation 
3. operand 
4. comment 


The statement lines in the source file must not be numbered. The 
assembler will prefix each line with a sequential number, up to four 
decimal digits. 


The format of each line of source code is described in the following 
paragraphs. 


3.2.3.2 Label Field 


The label field is the first field in the source line. A label which 
begins in the first column of the line may be terminated by either a space 
or a colon. A label may be preceded by one or more spaces, provided it is 


then terminated by a colon. In neither case is the colon a part of the 
label. 


Labels are allowed on all instructions and assembler directives which 
define data structures. For such operations, the label is defined with a 
value equal to the location counter for the instruction or directive, 
including a designation for the program section in which the definition 
appears. 


Labels are required on the assembler directives which define symbol values 
(SET, EQU, REG). For these directives, the label is defined with a value 
(and for SET and EQU, a program section designation) corresponding to the 
expression in the operand field. 


Labels on MACRO definitions are saved as the mnemonic by which that macro 
is subsequently invoked. No memory address is associated with such 
labels. A label is also required on the IDNT directive. This label is 
passed on to the relocatable object module; it has no associated internal 
value. . 


No other directives allow labels. 


Labels which are the only field in the source line will be defined equal 
to the current location counter value and program section. 
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3.2.3.3 Operation Field 


The operation field follows the label field and is separated from it by at 
least one space. Entries in the field would fall under one of the 
following categories: 


a. Instruction mnemonics - which correspond to the 68000 
instruction set. 


b. Directive mnemonics - pseudo-operation codes for controlling the 
assembly process. 


c. Macro calls - invocations of previously-described macros. 


The size of the data field affected by an instruction is determined by the 
data size code. Some instructions and directives can operate on more than 
one data size. For these operations, the data size code must be specified 
or a default size of word (16-bit data) will be assumed. The size code 
need not be specified if only one data size is permitted by the operation. 
The data size code is specified by appending a period (.) to the operation 
field, followed by B, W, or L, where: 


= Byte (8-bit data) 
Word (the default size; 16-bit data) 
= Long word (32-bit data) 


B 
W 
L 


The data size code is not permitted, however, when the instruction or 
directive does not have a data size attribute. 


Examples (legal): 


LEA 2(A0),Al Long word size is assumed (.B,.W not allowed); this 
instruction loads effective address of first operand 
into Al. 

ADD .B ADDR, DO This instruction adds bytes whose address is ADDR to 


low order byte in DO. 


ADD D1,D2 This instruction adds low order word of Dl to low 
order word of D2. (W is the default size code. ) 


ADD.L A3 ,D3 This instruction adds entire 32-bit (long word) 
contents of A3 to D3. 


Example (illegal): 
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SUBA.B #5,Al1 Illegal size specification (.B not allowed on 
SUBA). This instruction would have attempted to 
subtract the value 5 from the low order byte of 
Al; byte operations on address registers are not 
allowed. 


3.2.3.4 Operand Field 


If present, the operand field follows the operation field and is separated 
from the operation field by at least one space. When two or more operand 
subfields appear within a statement, they must be separated by a comma but 
may not contain embedded spaces; e.g., Dl, D2 is illegal. In an 
instruction like ' ADD D1,D2' the first subfield (D1) is generally applied 
to the second subfield (D2) and the results placed in the second subfield. 
Thus, the contents of Dl are added to the contents of D2 and the result is 
saved in register D2. In the instruction ' MOVE D1,D2' the first subfield 
(D1) is the sending field and the second subfield (D2) is the receiving 
field. In other words, for most two-operand instructions, the general 
format ‘opcode source, destination’ applies. 


3.2.3.5 Comment Field 


The last field of a source statement is an optional comment field. This 
field is ignored by the assembler except for being included in the 
listing. The comment field is separated from the operand field (or the 
operation field, if there is no operand) by one or more spaces, and may 
consist of any ASCII characters. This field is important in documenting 
the operation of a program. 


3.2.4 ARITHMETIC OPERATIONS 


The 68000 instruction set includes the operations of add, subtract, 
multiply, and divide. Add and subtract are available for all data operand 
sizes. Multiply and divide may be signed or unsigned. Operations on 
decimal data (BCD) include add, subtract, and negate. The general form 
is: 


<operation>.<size> <source>,<destination> 


Examples: 
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ADD .W 


SUB.B 


D1,D2 


#5, (Al) 


Adds low order word of D1 to low order word of 
D2. 


Subtracts value 5 from byte whose address is 
contained in Al. 


3.2.5 MOVE INSTRUCTION 


The MOVE instruction is used to move data between registers and/or memory. 
The general form is: 


MOVE .<size> 


Examples: 


MOVE 


MOVE .L 


MOVE .W 


MOVE 


D1, D2 


XYZ, DEF 


#'A' , ABC 


ADDR, A3 


<source> ,<destination> 


Moves low order word of Dl into low order word of 
D2. 


Moves long word addressed by XYZ into long word 
addressed by DEF. 


Moves word with value of $4100 into word 
addressed by ABC. 


Moves word addressed by ADDR into low order word 
of A3. 


3.2.6 COMPARE AND CHECK INSTRUCTIONS 


The general formats of the compare and check instructions are: 


CMP.<size> 


CHK 


<operand 1 >,<operand 2 > 


<bounds> ,<register> 


where operand 1 is compared to operand 2 by the subtraction of operand 1 
from operand 2 without altering operand 1 or operand 2. 


Condition codes resulting from the execution of the compare instruction 
are set so that a "less than" condition means that operand 2 is less than 
operand 1, and "greater than" means that operand 2 is greater than operand 


oe 
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The CHK instruction will cause a system trap if the register contents are 
less than zero or greater than the value specified by "bounds." 


Examples: 

CMP.L ADDR,D1 Compares long word at location ADDR with 
contents of Dl, setting condition codes 
accordingly. 

CHK (AO) ,D3 Compares word whose address is in AO with low 


order word of D3; if check fails (see text), a 
system trap is initiated. 


3.2./ LOGICAL OPERATIONS 


Logical operations include AND, OR, EXCLUSIVE OR, NOT, and two logical 
test operations. These functions may be done between registers, between 
registers and memory, or with immediate source operands. The general form 
is: 


<operation>.<size> <source>,<destination> 
Example: 
AND D1,D2 Low order word of D2 received logical ‘and' of 


low order words in D1 and D2. 


The destination may also be the status register (SR). 


3.2.8 SHIFT OPERATIONS 


Shift operations include arithmetic and logical shifts, as well as rotate 
and rotate with extend. All shift operations may be either fixed with the 
shift count in an immediate field or variable with the count in a 
register. Shifts in memory of a single bit position left or right may 
also be done. The general form is: 


<operation>.<size> <count> ,<operand> 


Examples: 
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LSL.W = #5,D3 Performs a left, logical shift of low order word 
of D3 by 5 bits; .W is optional (default). 


ASR (A2) Performs a right, arithmetic shift of word whose 
address is contained in A2; since this is a 
memory operand, the shift is only 1 bit. 


ROXL.B D3,D2 Performs a left rotation with extend bit of low 
order byte of D2; shift count is contained in 
D3. 


3.2.9 BIT OPERATIONS 


Bit operations allow test and modify combinations for single bits in 
either an 8-bit operand for memory destinations or a 32-bit operand for 
data register destinations. The bit number may be fixed or variable. The 
general form is: 

<operation> <bitno> ,<operand> 


Examples: 


~BCLR #3,XYZ(A3) clears bit number 3 in byte whose address is 
given by address in A3 plus displacement of XYZ. 


BCHG D1,D2 Tests a bit in D2, reflects its value in 


condition code Z, and then changes value of that 
bit; bit number is specified in Dl. 


3.2.10 CONDITIONAL OPERATIONS 
Condition codes can be used to set and clear data bytes. The general form 
is: 

Scc <location> 


where ‘cc’ may be one of the following condition codes: 


CC or HS’ GE LS PL 
CS or LO GT GE T 

EQ HI MI vc 
F LE NE VS 
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Example: 


SNE (A5)+ If condition code "NE" (not equal) is true, then 
set byte whose address is in A5 to 1's; 
otherwise, set that byte to 0's; increment A5 by 
Li , 


3.2.11 BRANCH OPERATIONS 


Branch operations include an unconditional branch, a branch to 
subroutine, and 14 conditional branch instructions. The general form is: 


<operation>.<extent> <location> 
Examples: 
BRA TAG Unconditional branch to the address TAG. 
BSR SUBDO Branch to subroutine SUBDO. 
Bec.S NEXT Short branch to NEXT, on condition "cc," which 


may be one of the following condition codes . 
(note that T and F are not valid condition codes 
for conditional branch): 


CC or HS GT LT VC 
CS or LO HI MI Vs 
EQ LE NE 
GE LS PL 


All conditional branch instructions are PC-relative addressing only, and 
may be either one-~ or two-word instructions. The corresponding 
displacement ranges are: 


one-word -128...+127 bytes (8-bit displacement) 
two-word -32768...+32767 bytes (16-bit displacement) 


Forward references in branch instructions will use the longer format by 
default (OPT BRL). The default may be changes to the shorter format by 
specifying OPT BRS. The default extent may be overridden for a single 
branch operation by appending an "S" or "L" extent code to the instruction 
-~- for example: 


BRA.L LAB 
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A branch instruction with a byte displacement must not reference the 
statement which immediately follows it. This would result in an 8-bit 
displacement value of 0, which is recognized by the assembler as an error 
condition. 


Example (illegal): 


BEQ.S LAB1 LAB1 is the next memory word and, thus generates 
LAB1 MOVE 1,D0, an error. 


3.2.12 JUMP OPERATIONS 


Jump operations include a jump to subroutine and an unconditional jump. 
The general form is: 


<operation>.<extent> <location> 
Examples: 
JMP 4(A7) Unconditional jump to the location 4 bytes beyond the 
address in A?. 
JMP .L NEXT Long (absolute) jump to the address NEXT. 
JSR SUBDO Jump to subroutine SUBDO. 


Forward references to a label will use the long absolute address format by 
default (OPT FRL). The default may be changed to the shorter format by 
specifying OPT FRS. The default extent may be overridden on a single jump 
operation to a label by appending "S" or "L" as an extent code for the 
instruction. 


3.2.13 DBCC INSTRUCTION 


This instruction is a looping primitive of three parameters: condition, 
data register and label. The instruction first tests the condition to 
determine if the termination condition for the loop has been met and, if 
so, no operation is performed. If the termination condition is not true, 
the data register is decremented by one. If the result is -1, execution 
continues with the next instruction. If the result is not equal to -l, 
execution continues at the indicated location. Label must be within 
16-bit displacement. The general format of the instruction is: 
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DBcc <data register>,<label> 


where "cc" may be one of the following condition codes: 


CC or HS GE LS PL 

CS or LO GT LT  #£«'T 

EQ HI MI VC 

F LE NE VS 
Examples: 

LAB1 NOP 


DBGT DO,LABI 

DBLE D1, LAB2 

DBT D2,LAB1 

DBF D3, LAB2 
LAB2 


3.2.14 LOAD/STORE MULTIPLE REGISTERS 
This instruction allows the loading and storing of multiple registers. 
Its general format is: 
MOVEM.<size> <registers>, <location> (register to memory) 
MOVEM.<size> <location>, <registers> (memory to register) 
where size may be either W (default) or L. 
The <registers> specu may assume any combination of the following: 
R1/R2/R3, etc., means R1 and R2 and R3 
R1-R3, etc., means R1 through R3 


When specifying a register range, A and D registers cannot be mixed; e.g., 
AO-A5 is legal, but AO-DO is not. 


The order in which the registers are processed is independent of the order 
in which they are specified in the source line; rather, the order of 
register processing is fixed by the instruction format. 


Examples: 


MOVEM (A6)+,D1/D5/D7 Load registers Dl, D5 and D7 from 
| three consecutive (sign-extended) 
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words in memory, the first of which is 
given by the address in A6; A6 is 
incremented by 2 after each transfer. 


MOVEM.L A2-A6,-(A7) Store registers A2 through A6 in five 
consecutive long words in memory; A/7 
is decremented by 4 (because of .LO; 
A6 is stored at the address in A7; A7 
is decremented by 4; A5 is stored at 
the address in A7, etc. 


MOVEM (A7)+,A1-A3/D1-D3 Loads registers Dl, D2, D3, Al, A2, A3 
in order from the siz consecutive 
(sign-extended) words in memory, 
starting with address in A?7_ and 
incrementing A7 by 2 at each step. 


MOVEM.L A1/A2/A3 ,REGSAVE Store registers Al, A2, A3 in three 
consecutive long words starting with 
the location labeled REGSAVE. 


3.2.15 LOAD EFFECTIVE ADDRESS 


This instruction allows computation and loading of the effective address 
into an address register. The general format is: 


LEA <operand> ,<register> 
Example: 

LEA XYZ(A2,D5),Al Load Al with effective address 
specified by first operand; see later 
explanation of addressing mode 
"address register indirect with 
index’. 
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3.3 SYMBOLS AND EXPRESSIONS 


3.3.1 SYMBOLS 


Symbols recognized by the assembler consist of one or more valid 
characters (see Appendix B), the first eight of which are significant. 
The first character must be an uppercase letter (A-Z) or a period(.). 
Each remaining character may be an uppercase letter, a digit (0-9); a 
dollar sign ($), a period (.), or an underscore (_). 


Numbers recognized by the assembler include decimal, hexadecimal, octal, 
and binary values. Decimal numbers are specified by a string of decimal 
digits (0-9); hexadecimal numbers are specified by a dollar sign ($) 
followed by a string of hexadecimal digits (0-9, A-F); octal numbers are 
specified by an "at" sign (@) followed by a string of octal digits (0-7); 
binary numbers are specified by a percent sign (%) followed by a string of 
binary digits (0-1). 


Examples: 
Octal - An “at' sign followed by a string of octal 
: digits 

Example: @12345 

Binary - A percent sign followed by a string of binary 
digits 
Example: %10111 

Decimal = A string of decimal digits 
Example: 12345 

Hexadecimal - A dollar sign (S$) followed by a string of 


hexadecimal digits. 
Example: $12345 


One or more ASCII characters enclosed by apostrophes (') constitute an 
ASCII string. ASCII strings are left-justified and zero-filled (if 
necessary), whether stored or used as immediate operands. This left 
justification will be to a word boundary if one or two characters are 
specified, or to a long word boundary if the string contains more than two 
characters. (In order to specify an apostrophe within a literal or 
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string, two successive apostrophes must appear where the single 
apostrophe is intended to appear.) 


Examples: DC.L  ‘ABCD' 
Data ~* 79° 
DC.W Of! 
Deu. “Jeo 


3.3.2 SYMBOL DEFINITION CLASSES 


Symbols may be differentiated by usage into two general classes. Class 1 
symbols are used in the operation field of the instruction (see paragraph 
3.2.4 for field definitions); Class 2 symbols occur in the label and 
operand fields of the instruction. Assembler directives, instruction 
mnemonics, and macro names comprise Class 1 symbols; user-defined labels 
and register mnemonics are included in Class 2 symbols. 


A Class 1 symbol may be redefined and used independently as a Class 2 
symbol, and vice versa. As long as each symbol is used correctly, no 
conflict will result from the existence of two symbols of different 
classes with the same name. For example, the following is a legal 
instruction sequence: 


ADD D1, ADD 


ADD DS 2 


By its use as a Class 1 symbol, the first "ADD" is recognized as an 
instruction mnemonic; likewise, the second ADD is recognized as a Class 2 
symbol identifying a reserved storage area. The assembler differentiates 
a Class 1 symbol from a Class 2 symbol with the same name, thereby 
allowing two symbol table entries with the same name but different class. 


Macro labels are a special case because the same symbol will appear as the 
label (Class 2) in the MACRO definition and, subsequently, as an operation 
code mnemonic (Class 1) in invocation of that same macro. Macro labels 
are defined to be Class 1 symbols; their presence in the label field of a 
MACRO directive is ignored as a Class 2 symbol. Therefore, macro names 
may be redefined as Class 2 symbols without conflict. 


A symbol may not be redefined within the same class. For example, ADD 


(reserved Class 1 symbol) may not be redefined as a macro label (also 
Class 1), nor may "A5" (reserved Class 2 symbol) be redefined as a 
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statement or storage location label (also Class 2). A reserved symbol may 
be used only within its own class. 7 


3.3.3 USER-DEFINED LABELS 


Labels are defined by the user to identify memory locations in program or 
data areas of the assembly module. Each label has two attributes: the 
program section in which the memory location resides, and the offset from 
the beginning of that program section. 


Labels may be defined in the label field of an executable instruction or a 


data definition directive source line. It is also possible to SET or EQU 
a label to either an absolute or a relocatable value. 


3.3.4 EXPRESSIONS 


Expressions are composed of one or more symbols, which may be combined 
with unary or binary operations. Legal symbols in expressions include: 


a. User-defined labels and their associated absolute or relocatable 
values. 
b. Numbers and their absolute values. 


c. The special symbol "*", which identifies the present location 


counter value, which may be either absolute or relocatable. 


3.3.5 OPERATOR PRECEDENCE 


Operators recognized by the assembler include the following: 


a. Arithmetic operators: 


addition (+) 
subtraction (-) 
multiplication (*) 
division (/)  -- produces a truncated integer result 
unary minus C5) 
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b. Shift operators (binary): 


shift right (>>) -- the left operand is shifted to the 
right (and zero-filled) by the 
number of bits specified by the 
right operand. 

shift left (<<) -- analogous to >> 


c. Logical operators (binary): 


and 


(&) 
or (!) 


Expressions are evaluated with the following operator precedence: 


multiplication, division 
addition, subtraction 


1. parenthetical expression (innermost first) 
2. unary minus 

3. shift 

4. and, or 

Di 

6. 


Operators of the same precedence are evaluated left to right. All results 
(including intermediate) of expression evaluation are 32-bit, truncated 
integers. Valid operands include numeric constants, ASCII literals, 
absolute symbols, and relocatable symbols (with "+" and '"-" only). 


3.4 REGISTERS 

The 68000 has sixteen 32-bit registers (D0O-D7, AO-A7) in addition to a 
24-bit program counter and 16-bit status register. 

Registers DO-D7 are used as data registers for byte, word, and long word 
operations. Registers AOQ-A7 are used as software stack pointers and base 
address registers; they may also be used for word and long word data 


operations. All 16 registers may be used as index registers. 


Register A7 is used as the system stack pointer. 


The following register mnemonics are recognized by the assembler: 
DO-D7 Data registers. 


AO-A7 Address registers. 
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A7,SP Either mnemonic represents the system stack pointer of the 
active system state. 


USP User stack pointer. 
CCR Condition code register (low 8 bits of SR). 
SR Status register. All 16 bits may be modified in the 


supervisor state. Only low 8 bits (CCR) may be modified in 
user state. 


PC Program counter. Used only in forcing program 
counter-relative addressing (see page 3-30). 


3.4.1 VARIANTS ON INSTRUCTION TYPES 


Certain instructions allow a "quick" and/or an "immediate" form when 
immediate data within a restricted size range appears as an operand. 
These abbreviated forms are normally chosen by the assembler, when 
appropriate. However, it is possible for the programmer to "force’ such a 
form by appending a "Q" or "I" to the mnemonic opcode (to indicate "quick" 
or “immediate’, respectively) on instructions for which such forms exist. 
If the specified quick or immediate form does not exist, or if the 
immediate data does not conform to the size requirements of the 
abbreviated form, an error will be generated. 


Some instructions also have "address" variant forms (which refer to 
address registers as destinations); these variants append an "A" to the 
instruction mnemonic (e.g., ADDA, CMPA). This variant will be chosen by 
the assembler without programmer specification, when appropriate to do 
so; the programmer need specify only the general instruction mnemonic. 
However, the programmer may '"force' or specify such a variant form by 
appending the "A". If the specified variant does not exist or is not 
appropriate with the given operands, an error will be generated. 


The CMP instruction also has a variant form (CMPM) in which both operands | 
are a special class of memory references. The CMPM instruction requires 
postincrement addressing of both operands. The CMPM instruction will be 
selected by the assembler, or it may be specified by the programmer. 


The variations -- A, Q, I, and M <-- must conform to the following 
restrictions: 


A Must specify an address register as a destination, and cannot 
specify a byte size code (.B). 


cP oma cert neat ct TVONICS POR ESSA OC SPE Rt er BE PY AE PT SU RC CREE PS SN SRO NaS AEH mR HEAT NPN Mle A TAY EL An enV Th SO GAY IRAN 
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Q Requires immediate operand be in a certain size range. MOVEQ 
also requires longword data size. 


I The size of immediate data is adjusted to match size code of 
operation. 
M Both operands must be postincrement addresses. 


For example, the instruction 
ADDQ #9 ,DO Attempts to add value 9 to DO 


will cause an assembly error, because the immediate operand is not in the 
valid size range (1 through 8). 


Although the assembler will choose the appropriate opcode variation -- A, 
Q, I, or M -- when the suffix is not specified, the explicit encoding of 


the suffix with the basic opcode is recommended for the following 
purposes: 


a. For documentation, to make clear in the source language the 
instruction form that was assembled. 

b. To force a format other than that which the assembler would 
choose. For example, the assembler would choose the quick (Q) 


form for the instruction 


ADD #1,D4 Adds the value 1 to D4 via an ADDQ (2-byte) 
instruction. 


If the immediate (I) form was desired, the programmer would need 
to declare it explicitly, as follows: 


ADDI #1,D4 Adds the value 1 to D4 via an ADDI (4-byte) 
instruction. 


c. To generate invariant code when using variant immediate data 
(separate assemblies). 


3.4.2 ADDRESSING MODES 


Effective address modes, combined with operation codes, define the 
particular function to be performed by a given instruction. 
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References to data addresses may be odd only if a byte is referenced. 
Data references involving words or long words must be even. Likewise, © 
instructions must begin on an even byte boundary. 


Individual bits within a byte (operand for memory destinations) or long 
words (operands for D register destinations) may be addressed with the bit 
manipulation instructions (paragraph 3.2.4.10). Bits for a byte are 
numbered 7 to 0, with 7 being the most significant bit position and 0 the 
least significant. Bits for a word are numbered 15 to 0, with 15 being the 
most significant bit and O the least significant. Bits for a long word 
are numbered from 31 to 0, with 31 being the most significant bit position 
and 0 the least significant bit position. 


Table 3-1 summarizes the addressing modes defined for the 68000, their 
invocations, and significant constraints. 


Table 3-1. Address Modes 


a A a RS A a | 
| MODE | INVOCATION | COMMENTS | 
[a 
11) Register direct 


An 
Dn 
2) Memory address 
a) Simple indirect (An) 
b) Predecrement - (An) 
c) Postincrement (An)+ 


d) Indirect with 
displacement (16-bit) 


<absolute>(An) 
<comp lex> (An) 


e) Indirect with index 
(16- or 32-bit) plus 
displacement (8-bit) 


<absolute>(An,Ri) 


| | | 

| | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 
| | | | 


See ee ee eee Pe ve ee RE ATE ee ee OP ae ie a EE |e ee OR ee eT IT 
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Table 3-1. Address Modes (continued) 


ie eee eee ee ee Bye ge ee er Cs © a 
3) Special address 


——_---____—_ 


a) PC with <simple> Expression must be 
displacement (16-bit) backward, within 
current relocatable 
section. 
<abos lute>(PC) Forced PC-relative. 
<simple>(PC) Must fit within 16-bit 
<complex>(PC) signed field; resolved 
at assembly or link time. 
b) PC with index <simple>(PC) Expression must be 


(16- or 32-bit) plus 
displacement (8-bit) 


backward, within current 
relocatable section. 


<absolute>(PC,Ri)| Forced PC-relative; 


<simple>(PC,Ri) expression must be within 
c) Absolute (16- or <absolute> Expression must be 
32-bit) <complex> forward reference or not 
<simple> in current program 
section. 
d) Immediate (8-, 16-, #<absolute> 
or 32-bit) #<simple> 
##<comp lex> 


4) Implicit PC 
reference 


Invoked by conditional 
branch (Bcc) or DBcc 
instruction; the effec- 
tive address is a 
displacement from the PC; 
the displacement is either 
8 or 16 bits, depending 

on OPT BRS, OPT BRL, and 
whether these options are 
overridden on the current 


instruction. 
Le er a ek a a Fs ea ore ee a ok ae Bei ha Tete oe ee ght ce ed 


| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
: | : current program section. 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 
| | | 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


Table 3-2 provides a cross reference of operand formats and addressing 
modes. Given an operator of the format shown in the first column, the 
other columns show which addressing mode is indicated, depending on 
whether the expression is absolute, simple relocatable, or complex 
relocatable. 
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Table 3-2. 


| | ABSOLUTE | IMPLE RELOCATABLE |COMPLEX RELOCATABLE 
|PERAND FORMAT | <expr> | <expr> | <expr> 
|<expr>(An) | d(An) |d(PC,An) | d(An) 
| | | 

|<expr>(Dn) | invalid |d(Pc<Dn) * | invalid 
| | | | 
|<expr>(An,Ri) | d(An,Ri) |invalid | invalid 

| | | | 
|<expr> | absolute (W,L) |d(PC)* or absolute | absolute (W,L) 
| | | (W,L) | 
| | | | | 
|<expr>(PC) | d(PC) | d(PC) | d(PC) 
| | | | 
|<expr>(PC,Ri) | d(PC,Ri) * |d(PC,Ri) * | invalid 
| | | | 
| #<expr> | immediate(B,W,L)|immediate (W,L) | immediate (W,L) 


Cross-Reference: Effective Addressing Mode, Given 
Operand Format and <expr> Type 


| EFFECTIVE ADDRESSING MODE 


| *Must be within current program section. 
Pe en eechete  tonesl eae sate ema e tk he ee ee oe et tn eee eet ae an etter 


Listed below are definitions of the symbols used in Tables 3-1 and 3-2, 
and throughout the remainder of this section: 


An 
Dn 


Ri 


B,W,L 
~ d(An) 


d(An,Ri) 


d¢PC) 


-d(PC,Ri) 


Address register number "n" (0-7). 
Data register number "n" (0-7). 


Index register number "i"; may be any address (An) or data 


(Dn) register with optional ".W" or ".L" size designation (16 
vs 32 bits). 
Byte, word, long word data sizes. 


Address register indirect with displacement (d). 


Address register indirect with index (Ri) plus displacement 


(d). 
Program counter with displacement (d). 


Program counter with index (Ri) plus displacement (d). 
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<absolute> Absolute expression. 
<simple> Simple relocatable expression. 


<complex> Complex relocatable expression. 


3.4.2.1 Register Direct Modes 


These effective addressing modes specify that the operand is in one of the 
16 multifunction registers (eight data and eight address registers). The 
operation is performed directly on the actual contents of the register 


Notations: An 


Dn where n is between O and 7 
Examples: CLR.L Dl Clear all 32 bits of Dl. 
ADD Al,A2 Add low order word of Al to low order 
word of A2. 


3.4.2.2 Memory Address 


The following effective addressing modes specify that the operand is in 
memory and provide the specific address of the operand. 


ADDRESS REGISTER INDIRECT The address of the operand is in the 


address register specified by the register field. 
Notation: (An) 


Examples: MOVE #5,(A5) Move value 5 to word whose address is 
3 contained in A5. 


SUB.L (Al) ,DO Subtract from DO the value in the long 
word whose address is contained in Al. 


ADDRESS REGISTER INDIRECT WITH POSTINCREMENT The address of 
the operand is in the address register specified by the register field. 
After the operand address is used, it is incremented by one, two or four, 
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depending upon whether the size of the operand is byte (.B), word (.W), or 
long (.L). | | 


Notation: (An)+ 


Examples: MOVE.B (A2)+,D2 Move byte whose address is in A2 to 


low order byte of D2; increment A2 by 
Tse | 
MOVE.L (A4)+,D3 Move long word whose address is in A4 


to D3; increment A4 by 4. 


ADDRESS REGISTER INDIRECT WITH PREDECREMENT The address of the 
operand is in the address register specified by the register field. 
Before the operand address is used, it is decremented by one, two, or 


four, depending upon whether the operand size is byte (.B), word (.W), or 
long (.L). 


Notation: -(An) 


Examples: CLR -(A2) Subtract 2 from A2; clear word whose 
address is now in A2. 


CMP.L -(A0),DO Subtract 4 from AO; compare long word 
whose address is now in AO with 
contents of DO. 


ADDRESS REGISTER INDIRECT WITH DISPLACEMENT The address of the 
operand is the sum of the address in the address register and the 
sign-extended displacement. 


Notation: d(An) 


Examples: AVAL EQU 5 AVAL is equated to 5 (for use in 
next instruction). 


CLR.B AVAL(A0) Clear byte whose address is given by 
adding value of AVAL (=5) to 
contents of AO. 


MOVE #2,10(A2) Move value 2 to word whose address 


is given by adding 10 to contents of 
A2. 
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ADDRESS REGISTER INDIRECT WITH INDEX The address of the operand 
is the sum of the address in the address register, the sign-extended 
displacement, and the contents of the index (A or D) register. 


Notations: d(an,Ri) Specifies low order word of index register. 
d(An,Ri.W) 
d(An,Ri.L) Specifies entire contents of index register. 


Examples: ADD AVAL(A1,D2),D5 Add to low order word of D5 the word 
whose address is given by addition of 
contents of Al, the low order word of 
index register (D2), and the 
displacement (AVAL). 


MOVE.L D5,$20(A2,A3.L) Move entire contents of D5 to long 
word whose address is given by 
addition of contents of A2, contents 
of entire index register (A3), and the 
displacement ($20). 


3.4.2.3 Special Address Modes 


Special address modes use the effective address register field to specify 
the special addressing mode instead of a register number. The following 
table provides the ranges for absolute short and long addresses. 


32-bit address 16-bit representation of 32-bit address 
Foe re em a, cee wae ee Ree ety Me eee ee ee ee re ee er ee ee ee a 
| 00000000 | 0000 | 
| : : Absolute short 
| 0O0O007FFF | 7FFF | 
Po 
| 
| 
| 
| 


——d 


00008000 


| 
| 
| must be absolute long) 
| 


| | 

(No representation in 16 bits; | 

. | 
FFFF7FFF | 


FFFF8000 8000 


| 
| ; Absolute short 
| 
| 


ee ee ee 


FFFFFFFF FFFF 


I a a se ee 
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ABSOLUTE SHORT ADDRESS The 16-bit address of the operand is sign 
extended before it is used. Therefore, the useful address range is 0 
through $7FFF and SFFFF8000 through SFFFFFFFF. 


Notation: XXX 


Example: JMP $400 Jump to hex address 400 


ABSOLUTE LONG ADDRESS The address of the operand is the 32-bit 


value specified. 
Notation: KXX 


Exmaple: JMP §$12000 Jump to hex address 12000 


PROGRAM COUNTER WITH DISPLACEMENT The address of the operand is 
the sum of the address in the program counter and the sign-extended 
displacement integer. The assembler calculates this sign-extended 
displacement by subtracting the address of displacement word from the 
value of the operand field. 


Notation: <expression>(PC) Forced program counter-relative. 
Example: | JMP TAG (PC) Force the evaluation of 'TAG' to be 


program counter-relative. 


PROGRAM COUNTER WITH INDEX The address is the sum of the address 
in the program counter, the sign-extended displacement value, and the 
contents of the index (A or D) register. 


Notations: <expression>(Ri.W) Specifies low order word of index 
register. .W is optional (default). 


<expression>(Ri.L) Specifies entire contents of index 
register. 
<expression>(PC,Ri) Forced program counter-relative. 


Ri.W or Ri.L legal. 


Examples: MOVE T(D2) , TABLE Moves word at location (T plus 
contents of D2) to word location 
defined by TABLE. T must be a 
relocatable symbol. 


JMP TABLE (A2.W) Transfers control to location defined 
by TABLE plus the lower 16-bit content 


Computer System Macro Assembler 3-28 


of A2 with sign extension. TABLE must 
be a relocatable symbol. 


JMP TAG(PC,A2.W) Forces evaluation of 'TAG' to be 
program counter-relative with index. 


IMMEDIATE DATA An absolute number may be specified as an operand by 
immediately preceding a number or expression with a ‘#' character. The 
immediate character (#) is used to designate and absolute number other 
than a displacement or an absolute address. 


Notation: #XxXX 
Examples: MOVE #1,D0 Move value 1 to low order word of DO. 


SUB.L #1, D0 Subtract value 1 from the entire 
contents of DO. 


3.4.3 NOTES ON ADDRESSING OPTIONS 


By default, the assembler will resolve all forward references by using the 
longer form of the effective address in the operand reference. The 
programmer may override this default by specifying OPT FRS, which 
designates that forward absolute references should be short, or OPT BRS, 
designating that forward relative branches should use the shorted (8-bit) 
displacement format. 


On an instruction which does not allow a size code, the current forward 
reference default format may be overridden (for that instruction only) by 
appending .S (short) or .L (long) to the instruction mnemonic. A similar 
override may be performed in the structured syntax control directives via 
the extent codes (see paragraph 3.6.3 for further explanation). No 
override is possible on instructions with size code specification. 
Notably, this override procedure is possible on branch and jump 
instructions. 


The shorter form of the effective address for relative branch instructions 
is an 8-bit displacement; the longer format is a 16-bit displacement. For 
absolute jumps, the shorter effective address is the 16-bit absolute 
short; the longer format is the 32-bit absolute long mode. In the case of 
forward references in either relative branches or absolute jumps, if the 
shorter format is directed and the longer format is later found necessary 
when the reference is resolved, an error will occur. 
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References to symbols already defined, whether absolute or relative, are 
resolved by the assembler into the appropriate effective address, unless 
.5 or .L is forced on the instruction. 


A short form may be forced by following the instruction mnemonic with .S. 


Example: 
BEQ.S LOOP 1 If condition code 'EQ' (equal) is true, then 
branch to LOOP1 (using the short form of the 
instruction). 


In this case, the instruction size is forced to one word. An error will be 
printed if the operand field is not in the range of an 8-bit displacement. 


Since 8-bit value fields are not relocated, a Bcc.S instruction which 
branches to an XREF or other expression-required location is not allowed. 
Such an instruction format will result in an assembler error. A relative 
branch to a symbol known to be an KREF will employ the longer (16-bit) 
displacement, with resolution by the linkage editor. 


Default actions of the assembler have been chosen to minimize two common 
address mode errors: 


a. Displacement range violations 


Relative branch instructions (Bcc, BRA, BSR) allow either 8-bit 
or 16-bit displacements from the PC. On forward references in 
such instructions, the default action is to assume the 16-bit 
displacement (OPT BRL), which also allows resolution by the 
linkage editor, should that prove necessary. 


b. Inappropriate absolute short address 


Absolute addresses may be short (16-bit) or long (32-bit). On 
forward references with absolute effective address, the default 
action is to assume the long format (OPT FRL). 


Default conditions have been chosen to prevent errors by using addressing 
formats which ensure address resolution in the broadest range of 
conditions, at the expense of code efficiency. Each default may be 
overridden to improve efficiency or to create position independent code. 
Also, the current address size defaults (options BRL, BRS, FRL, FRS) may 
be overridden in certain cases on specific instructions which do not allow 
Size codes by appending .S or .L, as in Bec,S and JMP.L (Bcc, BSR, JMP, JSR 
only). 
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3.5 ASSEMBLER DIRECTIVES 


3.5.1 INTRODUCTION 


All assembler directives (pseudo-ops), with the exception of "DC" and 
"DCB", are instructions to the assembler rather than instructions to be 
translated into object code. This chapter contains descriptions and 
examples of the basic forms of the most frequently used assembler 
directives. Directives controlling the macro and conditional assembly 
capabilities are described in Section 3.5. Directives used in structured 
syntax are described in Section 3.6. The most commonly used directives 
supported by the assembler are grouped by function in Table 3-3. 


Table 3-3. 68000 Assembler Directives 


ay ea ee ee ee ee ee 


DIRECTIVE | FUNCTION | 


ASSEMBLY CONTROL 


INCLUDE Include second file 
OFFSET Define offsets 
END Program end 


ee ee ee ee 


SYMBOL DEFINITION 


EQU* Assign permanent value 
SET* Assign temporary value 
REG* Define register list 


er ce ee 
ee ee 
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Table 3-3. 68000 Assembler Directives (cont'd) 


I ee a ee re Og ee ery ee ee Re eee eg ie ae me ey eS 
| DIRECTIVE | FUNCTION | 


‘DATA DEFINITION 
STORAGE ALLOCATION 


Define constants 
DS** Define storage 
DCB** Define constant block 


| 
| 
| DC** 
| 
| 
| 


LISTING CONTROL 
AND OPTIONS 


| | | 
| | | 
| | | 
| | | 
| PAGE | Top of page | 
| LIST | Enable the listing | 
| NOLIST or NOL | Disable the listing | 
| FORMAT | Enable the automatic formatting | 
| NOFORMAT | Disable the automatic formatting | 
| SPC n | Skip n lines | 
| NOPAGE | Disable paging | 
| LLEN n | Set line lengths 72S n $132 | 
| TTL | Up to 60 characters of title | 
| NOOBJ | Disable object output | 
| OPT | Assembler options | 
| FAIL |  Programmer-generated ERROR | 
| | | 


LINKAGE EDITOR CONTROL 


XDEF External symbol definition 


| | | 
| IDNT* | Relocatable identification record | 
| | | 
| XREF | External symbol reference | 
| | | 


| ** Label optional. | 
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3.5.2 ASSEMBLY CONTROL 


3.5.2.1 END - Program End 


FORMAT: 


DESCRIPTION: 


END [<start address>] 


END directive indicates to the assembler that the source 
is finished. Subsequent source statements are ignored. 
The END directive encountered at the end of the first pass 
through the source program causes the assembler to start 
the second pass. The start address should be specified 
unless it is external to the module. If no start address 
is specified, it is still possible to include a comment 
field, provided the comment field is set off by an 
exclamation point(!). This syntax indicates to the 
assembler that the operand field is null, but that a 
comment field follows. 


3.5.2.2 OFFSET - Define Offsets 


FORMAT: 


DESCRIPTION: 


OFFSET <expression> 


The OFFSET directive is used to define a table of offsets 
via the Define Storage (DS) directive without passing 
these storage definitions on to the linkage editor, in 
effect creating a dummy section. Symbols defined in a 
OFFSET table are kept internally, but no code-producing 
instructions or directives may appear. SET, EQU, REG, 
XDEF, and XREF directives are allowed. 


<expression> is the value at which the offset table is to 
begin. The expression must be absolute and may not contain 


forward, undefined, or external references. 


OFFSET is terminated by an ORG, OFFSET, SECTION, or END 
directive. 
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3.5.2.3 INCLUDE - Include Secondary File 


FORMAT: INCLUDE <file spec> 


DESCRIPTION: This directive is inserted in the source program at any 
point where a secondary file is to be included in the 
source input stream. 


3.5.3 SYMBOL DEFINITION 


Symbol definition directives EQU, REG, and SET provide the only method by 
which a symbol appearing in the label field may be assigned a 'value' 
other than that corresponding to the current location counter. 


3.5.3.1 EQU - Equate Symbol Value 


FORMAT: <label> EQU <expression> [<comments>] 

DESCRIPTION: EQU directive assigns the value of the expression in the 
operand field to the symbol in the label field. The label 
and expression follow the rules given in Section 3.2 . The 


label and operand fields are both required and the label 
cannot be defined anywhere else in the program. 


The expression in the operand field of an EQU cannot 
include a symbol that is undefined or not yet defined (no 
forward references are allowed). 


3.5.3.2 SET - Set Symbol Value 


FORMAT: <label> SET <expression> [<comments> ] 


DESCRIPTION: SET directive assigns the value of the expression in the 
operand field to the symbol in the label field. Thus, the 
SET directive is similar to the EQU directive. However, 
the SET directive allows the symbol in the label field to 
be redefined by other SET directives in the program. The 
label and operand fields are both required. 
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The expression in the operand field of a SET cannot include 
a symbol that is undefined or not yet defined (no forward 
references are allowed). 


3.5.3.3 REG - Define Register List 


FORMAT: <label> REG <reg list> [<comment> ] 


DESCRIPTION: REG directive assigns a value to <label> that can be 
translated into the register list mask format used in the 
MOVEM instruction. The label cannot be redefined as a 
Class 2 symbol anywhere else in the program. <reg list> is 
of the form: 


R1[-R2][/R3[-R4]]... 


Example: A1-A5/D0/D2-D4/D7 


3.5.4 DATA DEFINITION AND STORAGE ALLOCATION 


The directives in this section provide the only means by which object code 
may begin or end on odd byte boundaries. All instructions and all word or 
long word-sized data must begin and end on even byte boundaries. Odd byte 
alignment is allowed only for the DC.B, DS.B, DCB.B, and COMLINE 
directives. All other operations which generate relocatable object code 
will be preceded by a zero fill byte if word boundary alignment is 
required. 


3.5.4.1 DC - Define Constant 


FORMAT: [<label>] DC.B <operand(s)> Define constant in bytes 
DC.W <operand(s)> Define constant in words 
(default) 


DC.L <operand(s)> Define constant in long words 


DESCRIPTION: The function of the DC directive is to define a constant in 
memory. The DC directive may have one operand, or multiple 
operands which are separated by commas. The operand field 
may contain the actual value (decimal, hexadecimal, or 
ASCII). Alternatively, the operand may be a symbol or 
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expression which can be assigned a numeric value by the 
assembler. The constant is aligned on a word boundary if 
word (.W) or long word (.L) is specified, or a byte 
boundary if byte (.B) is specified. Only word (.W) and 
long word (.L) constants may be relocated. 


The following rules apply to size specifications of DC 
directives with ASCII string as operands: 


DC.B One byte is allocated per ASCII character. 


DC.W The string will begin on a word boundary. If the 
string address contains an odd number of characters, 
a zero fill byte will follow the last character. 


DC.L The string will begin on a word boundary. If the 
string length is not a multiple of four bytes, the 
last long word will be zero filled. 


Unless option CEX is in effect, a maximum of six 
bytes of constants will be displayed on the assembly 
listing. 


EXAMPLES OF ASCII STRINGS 


DC.B 'ABCDEFGHI' Memory would have nine contiguous bytes with the ASCII 


DC .L 


"12345! 


characters A through I. 


Memory will have characters "EJ" ($454A) in contiguous 
bytes. 


_ Memory will have $45004500 in contiguous bytes, the 
first zero byte being an odd byte fill as outlined 
above. 


Memory will have $5800 in contiguous bytes. 


Memory will have $3132333435000000 in contiguous 
bytes. 


EXAMPLES OF NUMERIC CONSTANTS 


DC .W 


10,5,/7 


10,5,7 


Memory would have three contiguous bytes with the 
decimal values 10, 5, and 7 in their respective bytes. 


Each operand is contained in a word. The value 10 is 
contained in the first word, right justified. The 
value 5 is in the second word, and the value 7 is in 
the third word. 
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DC.L 10,5,7 Each operand in a long word. The value 10 is contained 
in the first long word (4 bytes) right justified. The 
value 5 is in the second long word, and the value 7 is 
in the third long word. 


DC LABEL+1 The generated value will be the address of LABEL plus 1 
in a word size operand. 


DC SFF,$10,SAE Rules for hexadecimal are same as decimal. 
If the resulting value in an operand expression exceeds the size of the 
operand, an error is generated. For example, 


DC.B SFFF This will cause an error because SFFF cannot be 
represented in 8 bits. 


DC SFFF6F This will cause an error because SFFF6F cannot be 
represented in 16 bits. 


3.5.4.2 DS - Define Storage 


FORMAT: [<label>] DS.B <operand> Define storage in bytes 
DS.W <operand> Define storage in words 
(default) 
DS.L <operand> Define storage in long words 
DESCRIPTION: DS directive is used to reserve memory locations. The 
contents of the memory reserved is not initialized in any 
way. 
EXAMPLES: 
DS.B 10 Define 10 contiguous bytes in memory 
DS 10 Define 10 contiguous words in memory 
PT1 DS $10 Define 16 contiguous words in memory 
PT2 DS.L 100 Define 100 contiguous long words in memory 


The label will reference the lowest address of the defined storage area. 
If word or long-word mode is specified, the storage area is aligned on a 
word boundary. If it is desired to force alignment on a word boundary, 
the directive DS 0 may be used. 


EXAMPLE: DS.B 1 RESERVE ONE BYTE 
DS 0 SET LOCATION COUNTER TO EVEN BOUNDARY 
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The operand must not include a forward reference (to an undefined symbol). 


3.5.4.3 DCB - Define Constant Block 


_ FORMAT: 


DESCRIPTION: 


[<label>] DCB[.<size code>] <length>,<value> [<comment>] 


DCB directive causes the assembler to allocate a block of 
bytes, words, or long words, depending upon the <size 
code> specified. If <size code> is omitted, word (.W) is 
the default size. The block length is specified by the 
absolute expression <length>, which may not contain 
undefined, forward, or external references. The initial 
value of each storage unit allocated will be the 
Sign-extended expression <value>, which may contain 
forward references. <length> must be greater than zero. 
<value> may be relocatable unless byte size (.B) is 
specified. 


3.5.5 LISTING CONTROL 


3.5.5.1 PAGE - Top of Page 


FORMAT: 


DESCRIPTION: 


PAGE 


Advance the paper to the top of the next page. The PAGE 
directive does not appear on the program listing. No label 
or operand is used, an no machine code results. 


3.5.5.2 Listing Output Options 


LIST - LIST THE ASSEMBLY 


FORMAT: 


DESCRIPTION: 


LIST 


Print the assembly listing on the output device. This 
option is selected by default. The source text following 
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the LIST directive is printed until an END or NOLIST 
directive is encountered. 


NOLIST - DO NOT LIST THE ASSEMBLY 
FORMAT: NOLIST or NOL 


DESCRIPTION: Suppress the printing of the assembly listing until! a LIST 
directive is encountered. 


FORMAT - FORMAT THE SOURCE LISTING 

FORMAT : FORMAT 

DESCRIPTION: Format the source listing, including column alignment (see 
Table 3-4) and structured syntax indentation. This option 
is selected by default. 

NOFORMAT - DO NOT FORMAT THE SOURCE LISTING 

FORMAT: NOFORMAT 


DESCRIPTION: The source listing will have the same format as the source 
input file. 


SPC - SPACE BETWEEN SOURCE LINES 

FORMAT: SPC n 

DESCRIPTION: Output n blank lines on the assembly listing. This has the 
same effect as inputting n blank lines in the assembly 


source. A blank line is defined by the assembler to be a 
line with only a carriage return. 


NOPAGE - DO NOT PAGE SOURCE OUTPUT 
FORMAT: NOPAGE 
DESCRIPTION: Suppress paging to the output device. Output lines are 


printed continuously with no page headings or top and 
bottom margins. 


LLEN - LINE LENGTH 
FORMAT: LLEN n 
DESCRIPTION: Set the number of columns to be output to n. The minimum 


value of n is 72 and the maximum 132. The default value 
for n is 132 columns. 
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TTL - TITLE 
FORMAT: 


DESCRIPTION: 


TTL <title string> 


Print the <title string> at the top of each page. A title 
consists of up to 60 characters. The same title will 
appear at the top of all successive pages until another TT] 
directive is encountered. In order to print a title on the 
first listing page, the TTl directive must precede the 
first source line which will appear on the listing. 


NOOBJ - NO OBJECT 


FORMAT: 


DESCRIPTION: 


NOOBJ 


Suppress the generation of object code. 


OPT - ASSEMBLER OUTPUT OPTIONS 


FORMAT: 


DESCRIPTION: 


OPTIONS: 


OPT <option>| ,<option>]... [<comment> | 
Follows the command format. 


A Absolute address. All non-indexed operands which 
reference either labels or the current assembler 
location counter (*) will be resolved as absolute 
addresses. 


NOA Disable A (default). 


BRL Forward branch long (default). Forward references 

: in relative branch instructions (Bcc, BRA, BSR) 

will assume the longer form (16-bit displacement, 
yielding a 4-byte instruction). 


BRS Forward branch short. As with BRL, but using the 
: shorter form (8-bit displacement, yielding a 2-byte 
instruction). 
CEX Print DC expansions. 
NOCEX Opposite of CEX (default). 


CL Print conditional assembly directives (default). 


NOCL Opposite of CL. 


4 


CRE Print cross-reference table at end of source 
listing. This option must precede first symbol in 
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FRL 


FRS 


NOPCO 


PCS 


NOPCS 


source program. If this option is not in effect, 
only the symbol table will be printed. 


Debug option (output symbol table to file with the 
Same name as the object code file, but with an 
extension of '.RS"). 


Forward reference long 
references in the absolute 
absolute long mode (32-bit). 


(default). Forward 
format will assume 


Forward references in the 
format will assume absolute short mode 


Forward reference short. 
absolute 
(16-bit). 
Print macro calls (default). 
Opposite of MC. 

Print macro definitions (default). 
Opposite of MD. 

Print macro expansions. 

Opposite of MEX (default). 

Create output module (default). 

Opposite of O. 

PC relative addressing within ORG. Employ relative 
addressing when possible on backward references 
occurring in an ORG section. 

Disable PCO (default). 

Force PC relative addressing. This option may be 
used to force position independent code (see 
Section 3.7); however, this option does not force 
PC relative addressing of unknown forward 


references. 


Disable PCS (default). 
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3.5.6 FAIL - PROGRAMMER GENERATED ERROR 


FORMAT: 


DESCRIPTION: 


FAIL <expression> 


The FAIL directive will cause an error or warning message 
to be printed by the assembler. The total error count or 
warning count will be incremented as with any other error 
or warning. The FAIL directive is normally used in 
conjunction with conditional assembly directives for 
exceptional condition checking. The assembly proceeds 


normally after the error has been printed. The 
<expression> is evaluated and printed as the error or 
warning number on the assembly listing. Errors are 


numbered 0-499; warnings are numbered 500 and above. 


3.5.7 LINKAGE EDITOR CONTROL 


3.5.7.1 IDNT 


FORMAT : 


DESCRIPTION: 


3.5.7.2 XDEF 


FORMAT: 


DESCRIPTION: 


- Relocatable Identification Record 


<module name> IDNT <version>,<revision> [<descr>] 


Every relocatable object module must contain = an 
identification record as a means of identifying the module 
at link time. The module name is specified in the label 
field or the JIDNT directive, while the version and 
revision numbers are specified as the first and second 
operands, respectively. The comment field of the IDNT 
directive is also passed on the linkage editor as a 
description of the module. 


- External Symbol Definition 


XDEF <symbol>[,<symbol>]... [<comment> ] 


This directive specifies symbols defined in the current 
module that are passed on to the linkage editor as symbols 
which may be referenced by other modules linked to the 
current module. 
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3.5.7.3 XREF - External Symbol Reference 


FORMAT: 


DESCRIPTION: 


XREF[.S]  <symbol> [,<symbol>]... 
[,<symbol> [,<symbol>]...]... 


This directive specifies symbols referenced in the current 
module but defined in other modules. This list is passed 
on to the linkage editor. 


".S" indicates the XREF symbols will be linked into low 
address memory so that direct addressing of these symbols 
may be accomplished through absolute short mode. 


EXAMPLE: XREF AA,A2,A3,B3,C3 


3.6 INVOKING THE ASSEMBLER 


3.6.1 COMMAND LINE FORMAT 


ASM <sourcefile> [,option] ... 


sourcefile 


options 


+C [filename ] 


=C 


+L{ filename ] 


: Required. The default extension is ASM and will replace 
any other extension. 


: Can be specified in upper or lower case and in any order. 
If the same option is specified more than once, the last 
specification holds. Options must not be preceded by a 
blank. 


: Produce object code (default). If a filename is 
specified without an extension, the default extension 
.OBJ is added. If a filename is not specified, the 
output file created is sourcefilename. OBJ 


Inhibit production of object code. 


: Produce a listing file. If a filename is specified 
without an extension, the default extension .LST is 
added (unless the name begins with a #). If a filename 
is not specified, the listing file created is 
sourcefilename. LST 
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We suggest that you issue the commands SET LW=132 and SET 
LD=65 before listing assembler output on the printer. 


-L : Inhibit production of a listing file (default). 

+M : List macro expansions (if +L specified) 

-M : Inhibit listing of macro expansions (default). 

+R : Produce a cross-reference (if +L specified). 

-R : Inhibit production of a cross-reference (default) 

+§ : List structured control statement expansions (if +L 
specified). 

-S : Inhibit listing of structured control statement 


expansions (default) 
+W : Enable warning messages during assembly (default). 


-W : Disable warning messages during assembly. 


3.6.2 ASSEMBLER OUTPUT 

Assembler outputs include an assembly listing, a symbol table, and an 
object program file. 

The assembly listing includes the source program, as well as additional 
information generated by the assembler. Most lines in the listing 
correspond directly to a source statement. Lines which do not correspond 
directly to a source line include: 

° Page header and title 

ad Error and warning lines 

° Expansion lines for instructions over three words in length. 

The assembly listing format is shown in Table 3-4. The label, operation, 
and operand fields may be extended if the source field does not fit into 


the designated output field. 


The last page of the assembly listing is the symbol table. Symbols are 
listed in alphabetical order, along with their values and an indication of 
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the relocatable section in which they occur (if any). Symbols that are 
ADEF, XREF, REG, in named common, or multiply defined are flagged. If 
option CRE has been specified in the program, the cross-reference listing 
will identify the source lines on which the symbol was defined or 
referenced (definitions appear first, flagged with a "-"). 


An example of assembler output is provided in Appendix D. 


TABLE 3-4. Standard Listing Format 


eS ee rae Se ee I 
| COLUMN : CONTENTS | EXPLANATION | 
| | | | 
| 1-4 | Source line number | 4-digit decimal counter | 
| 6 ! section number ! l-digit hex section number 
| | | (blank indicates location counter | 
| | | is absolute) | 
: 8-15 | Location counter value | In hex : 
| 17-20 | Operand word : In hex : 
21-24 : First extension word : In hex ! 
25-28 | Second extension word : In hex; any additional extension : 
| | | words appear on the next line | 
30*37 : Label field | | 
! 39-46 | Operation field ! | 
: 48-67 : Operand field 
: 70-N ! Comment field | 
 ssaneusendntniadh spn cesta onacietentssenind/eie-syanes¥ancivicernesuie mesuctinennsnsttivetweeaepsc 


3.6.3 ASSEMBLER RUNTIME ERRORS 


During runtime, the assembler may generate its own error messages. These 
are listed in Appendix A. 
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Any assembly instruction which may generate six or more bytes of code, and 
that is found to have an operand error, will generate six bytes of object 
code. The code for instruction, however, will be S$4AFB, which is an 
illegal opcode, and the extension word(s) will be $4E71, which is a NOP. 
These six bytes allow more instructions to be patched in place, or a jump 
to be inserted to a patch area anywhere in the address space. 


Instructions which generate only two or four bytes will continue to 
generate a 2- or 4-byte length instruction, respectively, whenever an 
operand is in error. The instruction word, however, will be illegal and 
the extension will be a NOP. 


Undefined operations will generate six bytes of code with an illegal 
opcode and NOP extensions. 


3./ MACRO OPERATIONS AND CONDITIONAL ASSEMBLY 


3.7.1 INTRODUCTION 


This chapter describes the macro (paragraph 3.5.2) and the conditional 
assembly (paragraph 3.5.3) capabilities of the assembler. These features 
can be used in any program. 


3.7.2 MACRO OPERATIONS 


Programming applications frequently involve the coding of a repeated 
pattern of instructions that within themselves contain variable entries 
at each iteration of the pattern, or basic coding patterns subject to 
conditional assembly at each occurrence. In either case, macros provide a 
shorthand notation for handling these patterns. Having determined the 
iterated pattern, the programmer can, within the macro, designate fields 
of any statement as variable. Thereafter, by invoking a macro, the 
programmer can use the entire pattern as many times as_ needed, 
substituting different parameters for the designated variable portions of 
the statements. 


Macro usage can be divided into two basic parts -- definition and 
expansion. 
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When the pattern is defined it is given a name. This name becomes the 
mnemonic by which the macro is subsequently invoked (called). The name of 
a macro definition should not be the same as an existing instruction 
mnemonic, or an assembler directive. 


Expansion occurs when the previously defined macro is called (invoked). 
The macro call causes source statements to be generated. The generated 
statements may contain substitutable arguments. The statements that may 
be generated by a macro call are relatively unrestricted as to type. They 
can be any processor instruction, almost any assembler directive, or any 
previously defined macro. Source statements generated by a macro call are 
subject to the same conditions and restrictions to which programmer 
generate statements are subject. 


To invoke a macro, the macro name must appear in the operation field as a 
source statement. Most arguments are placed in the operand field. By 
suitably selecting the arguments in relation to their use as indicated by 
the -macro definition, the programmer causes the assembler to produce 
in-line coding variations of the macro definition. 


The effect of a macro call is the same as an open subroutine in that it 
produces in-line code to perform a predefined function. The in-line code 
is inserted in the normal flow of the program so that the generated 
instructions are executed in-line with the rest of the program each time 
the macro is called. 


3.7.2.1 Macro Definition 
The definition of. a macro consists of three parts: 


a. The header: label MACRO ¥ 


The label of the MACRO statement is the "“name' by which the macro 
is later invoked. This name must be a unique class 1 symbol. A 


macro name may not have a period (.) as any character other than 
the first. 


b. The body 


The body of a macro is a sequence of standard source statements. 
Macro parameters are defined by the appearance of argument 
designators within these source statements. Legal 
macro-generated statements include the set of 68000 assembly 
language instructions, assembler directives, structured syntax 
statements, and calls to other, previously defined macros. 
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However, macro definitions may not be nested. When macro text 
lines are saved for later expansion, all spaces in the source 
line are compressed. This space compression will be noticed only 
if the listing is unformatted, or if the macro text includes 
literal strings with multiple spaces (which would not expand 
correctly). Macro expansion lines which contain more than 80 
characters are truncated at 80 characters, which is the maximum 
length of an assembler input line. 


c. The terminator: ENDM 


3efi2;:2 Macro Invocation 


The form of a macro call is: [label] name[.qualifier] |parameter list] 


Although a macro may be referenced by another macro prior to its 
definition in the source module, the macro must be defined before its 
first in-line expansion. The name of the called macro must appear in the 
operation field of the source statement; parameters may appear as a 
qualifier to the macro name and/or in the operand field of the source 
statement, separated by commas. 


The macro call produces in-line code at the location of the invocation, 
according to the macro definition and the parameters specified in the 
macro call. The source statements so generated are then assembled, 
subject to the same conditions and restrictions affecting any source 
statement. Nested macro calls are also expanded at this time. 


3.7.2.3 Macro Parameter Definition and Use 


Up to thirty-six different, substitutable arguments may appear in the 
source statements which constitute the body of a macro. These arguments 


are replaced by the corresponding parameters in a subsequent call to that 
macro. 


Arguments are designated by a backslash character (\), followed by a digit 
(0 through 9) or an upper case letter (A through Z). Argument designator 
\O0 refers to the qualifier appended to the macro name; parameters in the 
operand field of the macro call refer to argument designations \1 through 
\9 and \A through \Z, in that order. 
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The parameter list (operand field) of a macro call may be extended onto 
additional lines if necessary. The line to be extended must end with a 
comma separating two parameters, and the subsequent extension line must 
begin with an ampersand (&) in column 1. The extension of the parameter 
list will begin with the first non-blank characters following the 
ampersand. No other source lines may occur within an extended parameter 
call, and no comment field may occur except after the last parameter on 
the last extension line. 


Argument substitution at the time of a macro call in handled as a literal 
(string) substitution. The string corresponding to a given parameter is 
substituted literally wherever that argument designator occurs in a 
source statement as the macro is expanded. Each statement generated in 
this expansion is assembled in-line. (Note that argument \0 begins with 
the first character following the period which separates the qualifier 
from the macro name, if a qualifier is present.) 


It is possible to specify a null argument in a macro call by an empty 
string (not a blank); it must still be separated from other parameters by 
a comma (except for \0). In the case of a null argument referenced as a 
size code, the default size code (W) is implied; when a null argument 
itself is passed as an argument in a nested macro call, a null argument is 
passed. All parameters have a default value of null at the time of a macro 
call. 


If an argument has multiple parts or contains commas or blanks, the entire 
argument must be enclosed within angle brackets (< and >). Such arguments 
must still be separated from other arguments by commas. A bracketed 
argument with no intervening character (<>) will be treated as a null 
argument. Embedded brackets must occur in pairs. Parameter \0O may not be 
bracketed and, hence, may not contain blanks (although commas are legal). 
Note that a macro argument may not contain the characters "<" or ">" 


unless they occur as part of the argument bracketing. 


3.7.2.4 Labels Within Macros 


To avoid the problem of multiply defined labels resulting from multiple 
calls to a macro which employs labels in its source statements, the 
programmer may direct the assembler to generate unique labels on each call 
to a macro. | 


Assembler-generated labels include a string of the form .nnn, where nn is 
a three-digit decimal number. The programmer may request an 
assembler-generated label by specifying \@ in a label field within a macro 
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body. Each successive label definition which specifies a \@ directive 
will generate successive values of .nnn, thereby creating unique labels on 
repeated macro calls. Note that \@ may be preceded or succeeded by 
additional characters for additional clarity and to prevent ambiguity 
(more than four preceding characters may introduce a problem with 
non-uniqueness of symbols). 


References to an assembler-generated label always refer to the label of 
the given form defined in the current level of macro expansion. Such a 
label is referenced as an operand by specifying the same character string 
as that which defines the label. 


3.7.2.5 The MEXIT Directive 


The MEXIT directive terminates the macro source statement generation 
during expansion. It may be used within a conditional assembly structure 
(see paragraph 3.5.3) to skip any remaining source lines up to the ENDM 
directive. All conditional assembly structures pending within the macro 
currently being expanded are also terminated by the MEXIT directive. 


Example: 

SAV2 MACRO 
MOVE. L \1,SAVET SAVE 1ST ARGUMENT 
MOVE. L \2,SAVET+4 SAVE 2ND ARGUMENT 
IFEQ "30,0 IS THERE A 3RD ARGUMENT? 
FAIL 1000 DID ASSEMBLER GO THRU HERE? 
MEXIT NO, EXIT FROM MACRO 
ENDC 
MOVE. L \3,SAVET+8 SAVE 3RD ARGUMENT 
ENDM 


3.7.2.6 NARG Symbol 


The symbol NARG is a special symbol when referenced within a macro 
expansion. The value assigned to NARG is the index of the last argument 
passed to the macros in the parameter list (even if nulls»). NARG is 
undefined outside of macro expansion, and may be referenced as a Class 1 
or 2 user-defined symbol outside of a macro expansion. 
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3.7.2.7 Implementation of Macro Definition 


When the sequence of source statements: 


~MAC1 


MACRO 
stmtl 
stmt2 


stmtn 
ENDM 


is encountered in a source program, the following actions are performed: 


3.7.2.8 


The symbol table is checked for a Class 1 symbol entry of 'MAC1’. 
If such an entry is already present, a redefined symbol error 
(231) is generated; if no such entry exists, an entry is placed 
in the symbol table, identifying MAC] as a macro. 


Starting with the line following the MACRO directive, each line 
of the macro body is saved in a character sequence identified 
with MAC1. In the example, stmtl through stmtn are saved in this 
manner.. No object code is produced at this time. A check is 
made for missing parameter references in the macro text (e.g., 
parameter \1, \2, and \4 are referenced, but \3 is not). 


Normal processing resumes with the line following the ENDM 
directive. 


Implementation of Macro Expansion 


When the statement: 


MAC1. qualifier paraml.parm2,...,paramn 


is encountered in a source program calling the previously defined macro 
MAC] (above), the following actions are performed: 
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Since the label field is blank, the string 'MAC1' is recognized 
as the operation code of the instruction. The symbol table is 
consulted for a Class 1 symbol entry with this name. If no such 
entry exists, an undefined symbol error (238) is generated. In 
this case, the entry indicates that the symbol identifies a 
macro. 


The rest of the line is scanned for parameters which are saved as 
literals of null values, one such value in each of the thirty-six 
parameter fields. If the source line ends with a comma, the next 
line is checked for an extension of the parameter list. A 
cross-check is made with the macro definition for the number of 
parameters in the call. No object code is produced. 


Macro expansion consists of the retrieval of the source lines 
which comprise the macro body. Each line is retrieved in turn, 
with special character pairs replaced by parameter strings or 
assembler-generated label strings. 


If a backslash character (\) is followed by either a digit (0 
through 9) or an uppercase letter (A through Z), the two 
characters are replaced by the literal string which corresponds 
to that parameter on the macro invocation lines(s). 


A character sequence which includes "\@" is replaced by an 
assembler-generated label, as defined in paragraph 3.5.2.4. An 
assembler-generated label is uniquely identified by the 
characters preceding and/or appended to the "\@" sequence and 
the macro invocation in which the reference occurs. Such labels 
may appear anywhere in the source line and will always refer to 
the current macro expansion. 


NOTE: Space compression is automatically done within macros. 
For example, the instruction DC.B ' ' becomes DC.B ' ' 


When a line has been completely expanded, the line assembled as 
any other source input line. At this time, any errors in the 
syntax of the expanded assembly code are found. Expanded lines 
longer than 80 characters are truncated and an error code is 
generated. 


If a nested macro call is encountered, the nested macro expansion 


takes place recursively. There is no set limit to the depth of 
macro call nesting. 
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3.7.3 CONDITIONAL ASSEMBLY 


Conditional assembly allows the programmer to write a comprehensive 
source program that can cover many conditions. Assembly conditions may be 
specified through the use of arguments in the case of macros, and through 
definition of symbols via the SET and EQU directives. Variations of 
parameters can then cause assembly of only those parts necessary for the 
specified conditions. 


The I/O section of a program, for example, will vary, depending on whether 
the program is used in a disk environment or in a paper tape environment. 
Conditional assembly directives can include or exclude an I/O section, 
based on a flag set at the beginning of the assembly. 


3.7.3.1 Conditional Assembly Structure 
The conditional assembly structure consists of three parts: 


a. The header 


There are two conditional clauses recognized by the assembler. 
The first form compares the equality of two strings: 


IFxx '<string>','<string2>' 
"xx" specifies either the string compare (C) condition or the 
string not compare (NC) condition, representing string equality 
and inequality, respectively. The result of the string 
comparison, along with the ‘xx’ condition, determines whether 
the body of the conditional structure will be assembled. Either 
string may contain embedded commas or spaces. An apostrophe that 


occurs within a string must be specified by double apostrophes. 


The second form of the conditional clause compares an expression 
against zero: 


IFxx expression 


"xx" specifies a conditional relation between the expression and 
the value zero. The result of this comparison at assembly time 
determines whether the body of the conditional structure will be 


assembled. Valid conditional relation codes include: 


EQ : expression = 0 
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NE : expression <> 0 
LT : expression < 0 
LE : expression <= 0 
GT : expression > 0 
GE : expression >= 0 


Because of the nature of this comparison, the expression must be 
absolute. No forward references are allowed. 


b. The body | 


The body of the conditional assembly structure consists of a 
sequence of standard source statements. There is no set limit to 
the depth of conditional assembly nesting; if such nesting 
occurs, a terminator must be specified for each structure. 


c. The terminator: ENDC 


When an IFxx directive is encountered, the specified condition is 
evaluated. If the condition is true, the statements constituting the body 
of the conditional assembly structure are each assembled in turn. If the 
relation is false, the entire conditional assembly structure is ignored; 
the ignored lines are not included in the assembly listing. By specifying 
the OPT NOCL option (paragraph 3.5.2.10), the header and terminator lines 
will be ignored for listing purposes. 


IFxx and ENDC directives may not be labeled. 


Testing for null parameters may be done via the string compare form of the 
conditional assembly. To assemble conditionally if parameter 1 is null, 
either of the following directives would be correct: 


IFxx ‘','\1' 
or 
IFxx ‘\1','' 


To assemble conditionally if a parameter is present would use either of 
the IFNC formats analogous to the above two. 


A conditional assembly structure is also terminated by a MEXIT directive, 
as explained in paragraph 3.5.2.5. All conditional assembly structures 
which originate in a macro are terminated at the exit from that macro (if 
not before). Only conditional assembly structures which originated 
within a given macro may be terminated within that macro. These two rules 
are necessary for the consistent implementation of conditional assembly. 
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3.7.3.2 Example of Macro and Conditional Assembly Usage 


The following example illustrates most of the features of macros and 
conditional assembly structures. The assembly code is shown as it would 
appear without line numbers or object code. 


MACO MACRO 


MOVE. \0 \1 
CLR.L \2 
ENDM 
MAC1 MACRO 
MOVE. \0 #\1,D\2 
IF\3 \1 CONDITIONAL 
ADD. \0 #1,D\2 
IF\3 \1-5 NESTED CONDITIONAL 
ADD.\O #2 ,D\2 \4 
ENDC END NESTED CONDITIONAL 
ENDC END CONDITIONAL 
LAB\@ CLR.L Dl 
MOVE. \0 D\2, (AO)+ 
B\3 \@END 
BRA LAB\@ 
\@END \5.\0 #1,D\2 
| IFLE \1 
MACO.\0 <D\2, (AO)>,A\2 NESTED MACRO CALL 
ENDC 
ENDM 
OPT MEX ,NOCL 
MAC1.L 7,3,GT,<TEST PASSES>, ADD 
MOVE. L #7 ,D3 
ADD. L #1,D3 
ADD. L #2 ,D3 TEST PASSES 
LAB.001 CLR.L D1 
MOVE. L D3, (AQ)+ 
BGT .002END 
BRA LAB.001 


.OO2END ADD.L #1,D3 
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MAC1 0,6,NE,<ERROR HERE>,SUB 


MOVE. #0, D6 
LAB .003 CLR.L D1 
MOVE. D6, (A0)+ 
BNE . OO4END 
BRA LAB .003 
. OO4END SUB. #1,D6 
MACO. <D6, (AO). ,A6 NESTED MACRO CALL 
MOVE. Dé, (A0) 
CLR.L A6 


3.8 STRUCTURED CONTROL STATEMENTS 


3.8.1 INTRODUCTION 


An assembly language provides an instruction set for performing certain 
rudimentary operations. These operations, in turn, may be combined into 
control structures -- such as loops, (for, repeat, while) or conditional 
branches (if-then, if-then-else). The assembler, however, accepts 
formal, highlevel directives that specify these control structures, 
generating, in turn, the appropriate assembly language instructions for 
their efficient implementation. This use of structured control statement 
directives improves the readability of assembly language programs, 
without comprimising the desirable aspects of programming in an assembly 
language. 


3.6.2 KEYWORD SYMBOLS 


% 


The following Class 1 symbols, used in the structured syntax, are reserved 
keywords (directives): 


ELSE ENDW REPEAT 
ENDF FOR UNTIL 
ENDI IF WHILE 
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The following symbols are required in the structured syntax, but are 
nonreserved keywords: 


AND DOWNTO TO 
BY OR 
DO THEN 


Note that AND and OR are reserved instruction mnemonics, however. 


3.8.3 SYNTAX 


The formats for the IF, FOR, REPEAT, and WHILE statements are found in 
paragraphs 3.6.3.1 through 3.6.3.4. They are spaced to show the line 
Separations required for Class 1 symbol usage (paragraph 3.6.5.1). 
Syntactic variables used in the formats area as follows: 


<expression> A simple or compound expression (paragraph 3.6.4). 


<stmtlist> Zero or more assembler directive (Section 3.3) occurring 
within a structured control statement is examined once - 
at assembly time. Thus, the presence of a directive within 
a FOR, REPEAT, or WHILE statement does not imply repeated 
occurrence of an assembler directive; nor does’ the 
presence of a directive within an IF-THEN-ELSE statement 
imply a conditional assembly structure (Section 3). 


<size> The value B, W, or L, indicating a data size of byte, word, 
or long, respectively. With the keyword FOR, <size> is a 
single code applying to <opl>, <op2>, <op3>, and <op4>. 
With the keywords IF, UNTIL, and WHILE, <size> indicates 
the size of the operand comparison in the subsequent 
simple expression (see paragraph 3.6.4.2 for a compound 
expression). 


<extent> The value S or L, indicating that the branch extent is 
short or long, respectively. This is appended to the 
keywords THEN, ELSE, and DO, to force the appropriate 
extent of the forward branch over the subsequent 
<stmtlist>. The default extent is determined by the 
option directive (OPT BRS or OPT BRL) currently in effect. 


<op1> A user-defined operand whose memory-register location will 


hold the FOR-counter. The effective address must be an 
alterable mode. 
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<op2> | The initial value of the FOR-counter. The effective 
address may be any mode. 


<op3> The terminating value for the FOR-counter. The effective 
address must be any mode. 


<op4> The step (increment/decrement) for the FOR-counter each 


through the loop. If not specified, it defaults to a value 
of #1. The effective address may be any mode. 


3.8.3.1 IF Statement 


SYNTAX: IF[.<size>] <expression> THEN[.<extent>] 
<stmtlist> 
ENDI 


Or 


IF[.<size>] <expression> THEN[.<extent>] 


<stmtlist> 
ELSE[ .<extent>] 
<stmtlist> 
ENDI 
FUNCTION: If <expression> is true, execute the <stmtlist> following 
THEN; if <expression> is false, execute the <stmtlist> 
following ELSE, if present, or advance to next 
instruction. 
NOTES: a. If an operand comparison <expression is specified, the 
condition codes are set and tested before execution of the 
<stmtlist>. 


b. In the case of nested IF-THEN-ELSE statements, each 
ELSE will refer to the closest IF-THEN. 


3.8.3.2 FOR Statement 


SYNTAX: FOR[.<size>]  <opl> = <op2> TO <op3> [BY  <op4>] 
DO[ .<extent> | 
<stmtlist> 
ENDF 
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FUNCTION: 


NOTES: 


Or 


FOR[.<size>] <opl> = <op2> DOWNTO <op3> [BY <op3>] 
DO[ .<extent> ] 

<stmtlist> 
ENDF 


These counting loops utilize a user-defined operand, 
<opl>, for the loop counter. FOR-TO allows counting 
upward, while FOR-DOWNTO allows counting downward. In 
both loops, the user may specify the step size, <op4>, or 
elect the default step size of ]1. The FOR-To loop is not 
executed if <op2> is greater than <op3> upon entry. 
Similarly, the FOR-DOWNTO loop is not executed if <op2> is 
less than <op3>. 


a. The condition codes are set and tested before each 
execution of the <stmtlist>. This happens even if 
<stmtlist> is not executed. 


b. A step size of ]1 may not be meaningful if the counter, 
<opl>, is used to index through word or longword-sized 
data. | 


c. Each immediate operand must be preceded by a "#' sign. 
For example, the following would loop ten times by steps of 
four. 


FOR COUNT = #4 TO #40 BY #4 DO... 
d. The FOR structure generates a move, a compare and either 


an add or subtract. Therefore, if any of the four operands 
is an A register, <size> may not be B (byte). 


3.8.3.3 REPEAT Statement 


SYNTAX: 


FUNCTION: 


NOTES : 


REPEAT 
<stmtlist> 
UNTIL[ .<size>] <expression> 


<stmtlist> is executed at least once, even if <expression> 
is true. | 


a. The <stmtlist> is executed at least once, even if 
<expression> is true upon entry. : 
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b. If an operand comparison <expression> is specified, the 
condition codes are set and tested following each 
execution of the <stmtlist>. 


3.8.3.4 WHILE Statement 


SYNTAX: WHILE[.<size>] <expression> DO[.<extent>] 
<stmtlist> 
ENDW 
FUNCTION: The <expression> is tested before execution of the 
<stmtlist>. While the <expression> is true, the 


<stmtlist> is executed repeatedly. 


NOTES: © a. If the <expression> is false upon entry, <stmtlist> is 
not executed. 


b. If an operand comparison <expression> is specified, the 
condition codes are set and tested before each execution 
of the <stmtlist>. The condition codes are set and tested 
even if the <stmtlist> is not executed. 


3.8.4 SIMPLE AND COMPOUND EXPRESSIONS 


Expressions are an integral part of IF, REPEAT, and WHILE statements. An 
expression may be.simple or compound. A compound expression consists of 
no more than two simple expressions joined by AND or OR. 


3.8.4.1 Simple Expressions 


Simple expressions are concerned with the bits of the Condition Code 
Register (CCR). These expressions are of two types. The first type 
merely tests conditions currently specified by the contents of the CCR. 
The second type sets up a comparison of two operands to set the condition 
codes, and afterwards tests the codes. 


CONDITION CODE EXPRESSIONS 


Fourteen tests (identical to those in the Bcc instruction) may be 
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performed, based on the CCR condition codes. The condition codes, in this 
case, are preset by either a user-generated instruction or a structured 
operand-comparison expression. Each test is expressed in the structured 


control statement by a mnemonic enclosed in angle brackets (< >), as 
follows: 


<CC> 
<CS> 
<EQ> 
<GE> 
<GT> 
<HI> 
<LE> 
<LS> 
<LT> 
<MI> 
<NE> 
<PL> 
<VC> 
<VS> 


For example: 


IF <EQ> THEN 
CLR.L D2 
ENDI 


REPEAT 
SUB 
D4,D3 
UNTIL <LT> 


OPERAND COMPARISON EXPRESSIONS 


Two operands may be compared in a simple expression with subsequent 
transfer of control based on that comparison. Such a comparison takes the 
form: 


<opl> <cc> <op2> 
where <cc> is a condition mnemonic enclosed in angle brackets (as 
described in paragraph 3.6.4.1.1), specifying the relation to be tested 
between <opl> and <op2>. When processed by the assembler, this expression 


translates to a compare instruction - for example: 


CMP <op1>,<op2> 
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followed by a branch instruction (Bcc) which tests the relation specified. 
<opl> is normally assigned to the first (leftmost) operand and <op2> to 
the second (rightmost) operand of the compare instruction. | 


A size may be specified for the comparison by appending a data size code 
(B, W, or L) to the directive, with W being the default. The only 
restriction is that a byte size code (B) may not be used in conjunction 
with an address register direct operand. | 


Compare instructions require certain effective addressing modes for their 
operands. These modes are listed in Table 3-5. However, if the operands, 
<opl> and <op2>, are not listed in an order that generated a legal compare 
instruction (Table 3-5), but that will generate a legal compare if the 
operand order is reversed, the assembler will reverse the operands when 
expanding the expression. To maintain the nature of the relation 
specified, the condition operator will also be adjusted, if necessary. 
For example, "D2 <GT> #5" would be adjusted by the assembler to the 
- equivalent of "#5 <LT> D2"; likewise, "A2 <EQ> (A5)" would be adjusted to 

the equivalent of "(A5) <EQ> A2". This processing allows the user 

flexibility of specifying the more meaningful operand order in the 
expression. 7 


TABLE 3-5. Effective Addressing Modes for Compare Instructions 


| EFFECTIVE ADDRESSING MODES FOR: 


indirect indirect 


| | COMPARE | | 

| INSTRUCTIONS | FIRST OPERAND SECOND OPERAND 

| | | 

| CMP | (All) | Data register direct 

| | | | 

| CMPA | (All) | Address register direct 
| | | 

| CMPI | Immediate | (Data alterable) 

| | | | 

| CMPM | Postincrement register | Postincrement register 
| | | 

| | | 
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If the operands, either as stated or reversed, do not yield a legal 
compare instruction, an error will result. For example, the statement 


IF (Al) <NE> (A2) THEN 
would result in an "ERROR 213" message - illegal address mode - during 


expansion. To avoid this error, a MOVE would be required to effect a 
legal operand, such as: 


MOVE (A2) ,D2 
IF (Al) <NE> D2 THEN 
Examples: 

WHILE .B (A3) <NE> D2 DO THIS EXPRESSION IS LEGAL AS STATED. 
MOVE .B (A5)+,D2 

ENDW | 

IF _ D7 <LT> #10 THEN THIS EXPRESSION WILL BE REVERSED. 
BRS SUBR1 

ELSE 
MULS #2 ,D7 

ENDI 


3.8.4.2 Compound Expressions 


A compound expression consists of two simple expressions (paragraph 
3.6.4.1) joined by a logical operator. The Boolean value of the compound 
expression is determined by the Boolean values of the simple expressions 
and the nature of the logical operator (AND or OR). 


The two simple expressions are evaluated in the order in which they are 
given. However, if an AND separates the expressions and the first 
expression is false, the second expression will not be evaluated. 

Likewise, if an OR separates the first expression is true, the second 
expression will not be evaluated. In these cases, the compound expression 
is either false or true, respectively, and the condition codes reflect the 
result of only the first simple expression. 


A size may be specified for each operand comparison expression. The size 
of the comparison for the first expression may be appended to the. 
directive, while the size of the comparison for the second expression may 


be appended to the keyword AND or OR. For example, in the statement 


IF.L D3 <GT> (AO) OR.B #'Q' <EQ> BUFFER1 
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the first comparison is a longword comparison, and the second is a byte 
comparison. : | 


3.8.5 SOURCE LINE FORMATTING 
3.8.5.1 Class 1 Symbol Usage 


Class 1 symbols, as described in paragraph 3.6.2, are the assembler 
directives (including macro names), instructions mnemonics and the 
structured control directives. Only one of these is recognized on each 
source line. Thus, each directive (reserved keyword) of a structured 
control statement and each executable instruction generated by the 
programmer must be written on a separate source line. The following 
source line, for example, is in error: 


REPEAT MOVE -(A5),D2 UNTIL <EQ> 


because the MOVE and UNTIL symbols and their operands are not recognized, 
but are treated as part of the comment field of the REPEAT directive. 
Likewise, the following lines are in error: 


IF <VS> THEN JSR OVERFLOW 
ELSE  JMP (A3) ENDI 


because the JSR, JMP, and ENDI symbols and their operands are not 
recognized. The correct format for these lines would be as follows: 


REPEAT 
MOVE -(A5) ,D2 
UNTIL <EQ> 
and 
IF <VS> THEN 
JSR OVERFLOW 
ELSE 
JMP (A3) 


ENDI 
3.8.6 LIMITED FREE-FORMATTING 


To improve readability, limited free-formatting allows the operand field 
of the IF, UNTIL, WHILE, and FOR directives to be extended onto additional 
consecutive lines. | | 
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For example: 
IF #15 <LT> D7 
AND 
(A3) <NE> D3 THEN 


UNTIL (A7)+ <EQ> D2 OR 
<VS> 


FOR D1 = #1 to #5 
BY #1 DO 


3.8.6.1 Nesting of Structured Statements 


Structured statements may be nested as desired to create multi-level 
control structures. An example of such nesting is the following: 


IF <EQ> THEN 
REPEAT 
MOVE DO, (A5)+ 
ADDQ #4 ,DO 


MOVE .L A4, (A4)+ 
UNTIL.L A5 <LE> A4 
ELSE. L 
FOR D2 = #10 TO #20 BY #2 DO 
WHILE D4 <LT> D2 AND D4 <LT> #100 DO 
MOVE.L 10(A3,D4.W), (A5)+ 
ADDQ #2 ,D4 
ENDW 
ENDF 
ENDI 


3.8.6.2 Assembly Listing Format 


By default (FORMAT directive), the assembly listings are formatted 
according to Table 3-4. In addition, the operation and operand fields of 
source lines in structures syntax are indented two columns for each nested 
level of operation. This automatic formatting may be turned off by using 
the NOFORMAT directive. 


The assembly language code generated for the structured syntax is included 
in the listing when the S option is specified in the ASM command line. 
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3.8.7 EFFECTS ON THE USER'S ENVIRONMENT 


If the S option is specified in the ASM command line (paragraph 3.4.1), 
the generated code of the structured control expansions is listed. There 


may be three items found in this code that will affect the user's 
environment: 


a. During assembly, local labels beginning with "ZL" are 
generated. These labels use the same increment counter (.nnn) as 
local labels in macros (see paragraph 3.5.2.4). They are stored 


in the symbol table and should not be duplicated in user-defined 
labels. 


b. In the FOR loop, <opl> is a user-defined symbol. When exiting 
the loop, the memory/register assigned to this symbol contains 
the value which caused the exit from the loop. 


c. Compare instructions (see Table 3-5) are generated by the > 
assembler whenever two operands are tested relationally in a 
structured statement. During runtime, however, these 
assembler-generated instructions set the condition codes of the 
CCR (in the case of a loop, the condition codes are set 
repeatedly). Any user-written code, therefore, either within or 
following a structured statement, that references the CCR should 
be attentive to the effect of these instructions. 


3.9 GENERATING POSITION INDEPENDENT CODE 


3.9.1 FORCING POSITION INDEPENDENCE 


When creating a relocatable program module, it is often desirable to 
ensure that all references to operands in relocatable sections are 
position independent effective addressed -- i.e., that no absolute 
addresses occur as effective addresses for such references. To avoid 
absolute effective address formats, it is necessary to ensure that all 
memory operand references are resolved by the assembler (or by the linkage 
editor at the assembler's direction) into one of the program counter 
relative or address register indirect addressing modes. Avoiding ORG 
directives is not sufficient to ensure position independence, since it is 
possible for the assembler to produce absolute effective address formats 
even when no absolute symbols have been defined. 
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For example, if an instruction references a symbol that is not yet 
defined, or is defined either in another section or as an XREF in an 
unspecified section, the default action of the assembler is to direct the 
linkage editor to resolve the reference by supplying the absolute address 
of the symbol. By specifying OPT PCS, all references known to be in a 
relocatable section will be resolved as a Program Counter (PC) relative 
address. However, this does not solve the problem of forward references, 
which would still default to absolute format. To override an absolute 
address mode when resolving the effective address format of an operand, 
the following formats may be used to force program counter relative 


addressing: 
a. Forcing program counter with displacement 
An operand of the form: LABEL(PC) 


will be resolved as a PC with displacement effective address, 
either by the assembler or by linkage editor (at the assembler's 


direction). If LABEL cannot be resolved into a 16-bit 
displacement from the program counter, an error will be 
generated. 


b. Forcing PC with index plus displacement 
An operand of the form: LABEL(PC,Rn) 


will be resolved as a PC with index plus displacement effective 
address by the assembler. Since the displacement in this mode is 
8 bits, the reference must be resolvable by the assembler. If 
LABEL cannot be resolved by the assembler into an 8-bit 
displacement from the program counter, an error will be 
generated. 


3.9.2 BASE-DISPLACEMENT ADDRESSING 


Although PC relative addresses have the advantage of position 
independence, such address formats are often not the most meaningful to 
the programmer when debugging an assembled module. There are many times 
when a programmer would prefer to see an address relative to a specified 
base - i.e., in a base-displacement format. This is especially true when 
addressing tables, arrays, and other data structures. Base-displacement 
references to a given location are "base relative’ and, therefore, fixed 
with respect to a given base address; PC relative references to that same 
location are different in each instruction. 


Computer System Macro Assembler 3-67 


Base-displacement addressing must be handled explicitly by the 
programmer. For example, if the following data area is declared: 


TEMP DS $40 
CONST DC $10 
ARRAY1 DS.L $10 
ARRAY2 DS.L $10 
RESULT DS.L $10 


the programmer may choose to load A6 with the address of TEMP and make 
references to the other data locations as displacements from this base 
address. For example, to move the first element of ARRAY] to Dl, the 
programmer may specify: 


MOVE .L ARRAY1-TEMP(A6) ,D1 


Indexing with the low order contents of DO may be added (as the array 
index): 


MOVE .L ARRAY1-TEMP (A6 ,D0) ,D1 


3.9.3 BASE-DISPLACEMENT IN CONJUNCTION WITH FORCED 
POSITION INDEPENDENCE 


Complete code position independence can be achieved by’ using 
base-displacement addressing in conjunction with the PCS option and the 
forced PC relative addressing scheme outlined in Paragraph 3.7.1. 
Although these techniques can be used to avoid all undesired absolute 
address formats,. there are significant limitations of PC relative 
addressing in a position independent program, as noted below: 


a. PC with displacement 


Pc with displacement effective addresses are only restricted by 
the 16-bit displacement field. A displacement greater than 32K 
bytes from the current PC cannot be resolved in this format. 


b. PC with index plus displacement 


The displacement field here is restricted to 8 bits, limiting the 
range of this format to a 128-byte diplacement from the current 
PC. This 8-bit displacement is not relocatable. Therefore, only 
symbols with a known displacement from the program counter may be 
resolved in a PC with index plus displacement format. 
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Operands in the alterable addressing category 


Neither PC relative mode is allowed as an alterable operand. 
This is a significant limitation in instructions which require 


an alterable operand, such as the destination operand in a MOVE 
instruction. 


By appropriate use of base registers, these limitations can be overcome. 
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4.0 LINKER AND LIBRARY UTILITIES 


4.1 INTRODUCTION 


The Linker (ALINK) and Library (LIBRARY) utilities are a pair of 
complementary programs that aid in the process of generating executable 
programs under the Computer System operating system. 


The Linker links or binds relocatable object-code modules, and optional 
modules from libraries, to form a program that is executable. 


The Library utility builds a library by combining one or more relocatable 
object-code modules. Such a library may contain frequently used 
procedures (such as the mathematical functions of FORTRAN) which can be 
used in subsequent link processes. 


4.1.1 BUILDING AN EXECUTABLE PROGRAM 


To get from the source file of a program to an executable object code 
file, the user must proceed as follows: 


1. The source file is compiled or assembled without errors. The result 
of compiling or assembling is a relocatable object-code file of type 

t t 

.OBJ . 


2. The relocatable object-code is linked, and may include run-time 
support libraries. The result is an executable code file of type 


.BIN. 


3. The program can then be run (executed) on the Computer System simply 
by typing its filename. 


The following sections in this manual describe the Linker and Librarian 
object-code management system. 
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4.2 LINKER 


The Linker is a utility which accepts files of relocatable object-code 
generated by the compilers and assembler, plus library files generated by 
the Library utility, and links or binds those into a form suitable for 
execution. 


As well as binding together relocatable modules from various language 
processors, the Linker can search libraries of commonly used functions, 
(such as the PASCAL run time environment), and link only those modules 
that are referenced into the final loadable output file. 


In order to link relocatable modules into an executable object-code file, 
the Linker requires the following pieces of information: 


° The optional name of the listing file where the Linker messages and 
memory map information is to be listed. If no listing file name is 
given, no memory map information is generated, and messages appear on 
the user's console. 


. The name of the object-code file on which to write the final linked 
output. 


° The name(s) of the file(s) from which the relocatable object-code is 
read. 


° A list of one or more libraries which are to be used to satisfy 
external references within the object-code file. 


When linking a mixture of Pascal or Fortran object modules and Assembler 
object modules, the main program must be in Pascal or Fortran. Note that 
the linker produces a jump to an external reference when this reference is 
defined in a different segment, so that the only communication between 
Assembler and high level language modules should be calls to entry points 
of routines. | 


4.2.1 INVOKING ALINK 
The command line format for ALINK is: 


ALINK maininfile[,infile][,+L=listfile][,+L][,+P=commandfilej|[,+P][,-P] 
[ ,+S=startadr][,+M=memsize][,+0O=outfile] 
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Where: 


maininfile 


infile 


+L=listfile 


+L 


+P=commandfile 


+P 


=P 


+S=startadr 


+M=mems ize 


The name of an object code file to which control will pass 
when the finished program is executed. The default 
extension for this file is .OBJ. The default extension is 
used if the user does not supply an extension. If no main 
input file is provided, then ALINK will use <outfile.OBJ> 
by default. 


The name of an object code file to be linked. The default 
extension for this file is .OBJ. The default extension is 
used if the user does not supply an extension. Up to 50 
input files and options may be specified. 


Commands ALINK to place its listing file on file 
<listfile>. The default extension for this file is .MAP. 
The default extension is used if the user does not supply 
an extension. If no +L= or +L option is given, no listing 
output is generated. 


Commands ALINK to place its listing file on file 
<mainfile.LST>. If no +L= or +L option is given, no 
listing output is generated. 


Commands ALINK to take further directives (options and 
input files) from <commandfile>. The default extension 
for this file is .CMD. The default extension is used if 
the user does not supply an extension. 


Commands ALINK to take further directives (options) from 
file <maininfile.CMD>, one to a line. 


Use no command file. 


Sets startadr as the address at which the linked output 
module will be loaded when it is executed. To specify 
startadr in hexadecimal, begin the number with a §$. The 
default load address is SEO000. If you specify an illegal 
number, the default value will be used. 


Makes memsize bytes of stack/heap available to the linked 
output module when it is executed. To specify memsize in 
hexadecimal, begin the number with a $. The default 
stack/heap size is 3276/7 bytes and the minimum stack/heap 
size is 4096 bytes. If you specify 0, all RAM available at 
run time will be used. If you specify an illegal number, 
the default value will be used. If a nonzero memsizZe is 
given, and that amount of RAM is not available at run time, 


Linker and Library Manager 4-3 


a message ‘Not enough stack/heap space’ will be printed at 
run time. 


outfile The name of a file which will be output from ALINK. The 

default extension for this file is .BIN. The default 
extension is used if the user does not supply an extension. 
If no +0O= option is used, the file <maininfile.BIN> is 
used. 


4.2.2 LINKER ERROR MESSAGES 


The Linker can display various error messages in the course of its 
operation. The error messages are self-explanatory. There are three 
grades of error messages, with different outcomes: 


Warnings are correctable errors. The error can be corrected and the 
link proceeds. For example, misspelling a filename will 
result in a message to the effect that the file cannot be 
opened, at which point the filename can be retyped. 


Errors are correctable in that the user can proceed with the link 
process, but the generated object-code file is not created 
properly. 


Fatal errors are those from which the Linker cannot correct or recover. 
In those cases the linker returns to the system, and a 
prompt appears on the command line. 


4.3 LIBRARY UTILITY. 


The Library Program binds compiled or assembled relocatable object~-code 
modules (.0BJ) into a collection called a library. The purpose of a 
library is to provide a repository for commonly used object modules that 
have to be present when linking (see the Linker description), such that 
the common modules end up bound together into the final executable code 
module. 


The library utility typically requires the following pieces of 
information from the user: 


e The name of the file which is to receive the listing (results and log) 
of the library process. 
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° The name of the file which is to contain the generated library when 
the library generation process is complete. 


° The name(s) of file(s) (with the .obj) suffix, which contain the 
constituent parts of the library to be generated. 


4.3.1 INVOKING THE LIBRARY PROGRAM. 


The command line format for the library program is: 


LIBRARY outfile,infile|[,infile]...[,infile][,+L=listfile][,+L][+P=promptfile][,+P] 


where: 

outfile The name of the file that LIBRARY will use for its output. 
The default extension for this file is .OBJ. The default 
extension is used if the user does not supply an extension. 

infile The name of a file which will be input to LIBRARY. The 


default extension for this file is .OBJ. The default 
extension is used if the user does not supply an extension. 


+P=promptfile Commands LIBRARY to take further directives (input files 
or options) from file <promptfile>. The default extension 
for this file is .CMD. The default extension is used if 
the user does not supply an extension. 


+P Commands LIBRARY to take further directives (input files 
or options) from file <outfile.CMD>, one to a line. 


+L=listfile Commands LIBRARY to place its listing file on file 
<listfile>. The default extension for this file is .LST. 
The default extension is used if the user does not supply 
an extension. If no +L= or +L option is given, no listing 
output is generated. 


+L Commands LIBRARY to place its listing file on file 
<outfile.LST>. If no +L= or +L option is given, no listing 


output is generated. 


If the Librarian cannot find the specified input file it issues a message 
to the effect: 


The file ‘whatever.obj' can't be opened 
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4.4 OBJECT FILE FORMATS 


This chapter describes the layout of the object-code files that the Linker 
and Librarian can process. 


4.4.1 NOTATION USED TO DESCRIBE OBJECT FILE FORMATS 


The symbol "::="" is read as "defined to be". Where a whole list of objects 
appear to the right of a "pile" of "::="" signs, it implies a choice of any 
of the objects. 

Objects enclosed in "angle brackets", "<" and 
which are defined in terms of other objects. 


tr. 1t 


> are syntactic objects 


An object followed by an asterisk sign, "*" 


, can be repeated "zero to many 
times" (the list of objects can be empty). 

An object followed by a plus sign, "+", can be repeated “one to many 
times" (there must be at least one of that object). 


4.4.2 LINKER FILE LAYOUT 


This section is a description of the Linker File at the "top level”. 
<Link File> <Module File> 
<Library> 
<Unit File> 
<Execute File> 


<Module File> 


<Module>* EOF mark 


<Library File> <Library Module Block>+ <Library Entry Block>+ 
<Module>+ <Text Block>* EOF Mark 


<Unit Block> <Module>+ <Text Block> EOF Mark 


<Unit File> 


<Executable Block> <Module>*' 


<Execute File> 
, <Quick Load Block> 


<Module> <Module Name Block> <Other Block>+ <End Block> 
Entry Block 


<Other Block> 
. | External Block 
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Start Block 

Code Block 

Relocation Block 

Common Relocation Block 

Common Definition Block 

Short External Block 

Data Initialization Block 

FORTRAN data area definition block 
FORTRAN data area Initialization Block 
FORTRAN Data Area Reference Block 
Executable Data Area Initialization Block 
FORTRAN Executable Data Area Reference Block 


4.4.3 BYTE-LEVEL DESCRIPTION OF LINKER BLOCKS 


All Linker and Librarian object-code blocks start with a single 
“identifier byte." This block identifier takes values from 80 (base 16) 
upwards. 
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4.4.3.1 #80 - Module Name Block 


byte --> 0 


£2 


20 


24 


80 
size 
module name 


segment name 
csize 


comments 


4.4.3.2 #81 


SSeS See 
| 80 | size (3 bytes) | 


| | module name | 
| (8 bytes) | 


| segment name = 
| (8 bytes) | 


| csize (4 bytes) | 


| comments (24 .. size-1l bytes) ... | 
CE 5 ee 


Hexadecimal 80 indicates a Module Name Block. 
Number of bytes in this block. 
Blank padded ASCII name of module. 


ASCII name of segment in which this module will 
reside. 


Number of bytes in the code block for this 
module. 


Arbitrary information - ignored by the Linker. 


- End Block 


byte SS Oo; 81 | size (3 bytes) | 
an 
4 | csize (4 bytes) | 
81 Hexadecimal 81 indicates this is an End Block. 
size Number of bytes in this block - it is always 
000008. 
csize Number of bytes in the code block for this 


module. 
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4.4.3.3 #82 - Entry Point Block 


byte --> 


82 


size 
link name 
user name 


loc 


comments 


pe er a Ae pe pet ay tk oe ae ge 

oj] 82 | size (3 bytes) | 
ee 

4 | link name | 

8 | (8 bytes) | 

12 | user name | 

| (8 bytes) | 

——_____—_—______| 

20 | loc (4 bytes) | 

|}-—--———_—_--— 
24 | comments (24 .. size-1 bytes) ... | 
Seth aS ce Se ee hee ee ee 


Hexadecimal 82 indicates this is an Entry Point 
Block 


Number of bytes in this block. 
Blank padded ASCII Linker name of entry point. 
Blank Padded ASCII user name of entry point. 


Location of entry point relative to this 
module. 


Arbitrary information - ignored by the Linker. 
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4.4.3.4 #83 - External Reference Block 


byte --> 0 | 83 | size (3 bytes) | 
4 | link name | 

8 | (8 bytes) | 
SS 

12 | user name | 

| (8 bytes) | 
er net ane eeeee 

20 | ref 1 (4 bytes) | 

24 | ref 2 (4 bytes) | 


| each reference consumes 4 bytes | 


| a | 
‘Sea 
16+4*n | ref n (4 bytes) | 
Ut a ie 


83 Hexadecimal 83 indicates this is an External 
Reference 

size Number of bytes in this block. 

link name Blank padded ASCII Linker name of external 
reference. 

user name Blank padded ASCII user name of external 
reference. : 

ref l Location of first reference relative to this 
module. : 

ref 2 Location of second reference relative to this 
module. 


Other references. 


ref n Location of last reference relative to this 
module. 
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4.4.3.5 #84 - Starting Address Block 


byte --> 


84 


size 
start 
gsize 


comments 


ee = ee ee 


0o| 84 | si 


4 | start 


ze (3 bytes) | 


(4 bytes) | 


8 | gsize (4 bytes) | 
pene c areenra tn onicnnsee 


12 | comments (12 .. 


size-1 bytes) ... | 


IEE ek hee Rete Se cera ea Oe a Ce Ie eI rE Ee | 


Hexadecimal 84 indicates this is a Starting 


Address Block. 


Number of bytes in this block. 


Starting address relative to this module. 


Number of bytes in the global data area. 


Arbitrary information - ignored by the Linker. 


4.4.3.6 #85 - Code Block 


85 
size 
addr 


object-code 


O | 85 | size (3 bytes) | 
| 
4 | addr (4 bytes) | 


8 | object-code (8..size-1 bytes) ... | 
ee ee 


Hexadecimal 85 


indicates this is a Code Block. 


Number of bytes in this block. 


Module-relative address of first code byte. 


The object-code - always an even number of 


bytes. 
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4.4.3.7 #86 - 32-Bit Relocation 


byte --> Oo; 86 | size (3 bytes) | 
vipat peeteatinaeencaa eto 

4 | addr 1 (4 bytes) | 

Lip iininenasnecrincteteciee ethane 

12 | addr 2 (4 bytes) | 


pe 2 


16 | each addr consumes 4 bytes | 
ta aria eemetaaeieiserininialaart neal 
| Se oy. 2 | 


12+4%*n | addr n (4 bytes) | 
Da a at Sn ee ee te ey 


86 Hexadecimal 86 indicates this is a 32-bit 
Relocation Block. 


size Number of bytes in this block. 
addr 1 Location of first address to relocate. 
addr 2 Location of second address to relocate. 


Locations of other addresses to relocate. 


addr n Location of last address to relocate. 
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4.4.3.8 #87 - Common Block Reference 


byte --> 0 
A 
12 
16 
20 
8+4%*n 
87 
size 


common name 


ref 1 


ref 2 


ref n 


87 | size (3 bytes) | 


common name | 
(8 bytes) | 


ref 1 (4 bytes) | 


ref 2 (4 bytes) | 


|each reference consumes 4 bytes | 


ref n (4 bytes) | 
Hexadecimal 87 indicates this is a Common Block 
Reference. 
Number of bytes in this block. 
Blank padded ASCII common block name. 


Location of first reference relative to this 
module 


Location of second reference relative to this 
module. 


Other references relative to this module. 


Location of last reference relative to this 
module. 
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4.4.3.9 #88 - Common Block Definition 


byte --> O| 88 | size (3 bytes). | 
4 | common name | | 


| (8 bytes) | | 
easel aka cee Oa 
12 | dsize (4 bytes) | 
Pessina noes erin oeeitintotiirt 


(16 | comments (16 .. size-1 bytes) ... | 
ee a ee RS ee eT Se = FS eS 


88 Hexadecimal 88 indicates this is a Common 
Block Definition 


size Number of bytes in this block. 

common name Blank padded ASCII common data area name. 
dsize Number of bytes in this common data area. 
comments Arbitrary information - ignored by the Linker. 


4.4.3.10 #89 - Short External Reference Block 


byte --> Oo| 89 | size (3 bytes) | 
4 | link name _ | 

| (8 bytes) | | 

Sueiesicks Sia Ae aie 

12 | user name | 


| (8 bytes) | 
| | | 
20 | ref 1 (2 bytes) | ref 2 (2 bytes) | 


18+2*n | a 2 | ref n (2 bytes) | 
ee cal ce Se Oe eee eae ROT CRC VC ae aera eee Mele ene 
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89 Hexadecimal 89 indicates this is a Short 
External Reference Block. 


size Number of bytes in this block. 

link name Blank padded ASCII Linker name of external 
reference. 

user name Blank padded ASCII user name of external 
reference. 

ref l Location of first reference relative to this 
module. 

ref 2 Location of second reference relative to this 
module 


Location of other references relative to this 
module. 


ref n Location of last reference relative to this 
module. 


4.4.3.11 #8A - FORTRAN Data Area Definition Block 


byte --> O| BA | size (3 bytes) | 
[~~ 

4 |. data area name | 

| (8 bytes) | 

12 | dsize (4 bytes) | 


Le 5 ee 


8A Hexadecimal 8A indicates this is a FORTRAN Data 
Area Definition Block. 


size Number of bytes in this block. 


data area name Blank padded ASCII name of FORTRAN fixed data 
area. 


dsize Size of this data area. 


Linker and Library Manager 4-15 


4.4.3.12 #8B - FORTRAN Data Area Initialization Block — 


byte --> O | 8B | size (3 bytes) | | 


a See 
4 | data area name | 
| (8 bytes) | 
12> 4 daddr (4 bytes) | 
16 | data occupies bytes 16 .. size-1 | 


| in the rest of the block oo * | 
ee SR 


8B Hexadecimal 8B indicates this is a FORTRAN Data 
| Area Initialization Block. | 


size Number of bytes in this block. 


data area name Blank padded ASCII name of FORTRAN fixed data 


area. 
daddr seaeetae address of this data. 
data The initialization data. 
00 * If the size of the data block is odd, there is 


one byte of 00 added to make the block an even 
number of bytes in size. _ 
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4.4.3.13 #8C 


byte --> 0 


16 


8+4%*n 


8C 


size 


data area name 


ref 1 


ref 2 


ref n 


- FORTRAN Data Reference Block 


| 8c 


oe 


size (3 bytes) | 


data area name | 
(8 bytes) | 


ref 1 (4 bytes) | 


ref 2 (4 bytes) | 


|each reference consumes 4 bytes | 


te 


ref n (4 bytes) | 


Hexadecimal 8C indicates this is a FORTRAN Data 
Area Reference Block. 


Number of bytes in this block. 


Blank padded ASCII name of FORTRAN fixed data 


area. 

Location 
Tocacacn 
Location 


Location 


of first reference. 
of second reference. 
of other references. 


of last reference. 
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4.4.3.14 #90 - Library Module Block 


byte --> 0 | 90s size (3 bytes) | 
4 | module name | 
| (8 bytes) | 


12° 4 msize (4 bytes) | 
 oetacerenr somecentenacrauined hia 


16 | caddr (4 bytes) | 
20 | taddr (4 bytes) | 
28 | module count | module 1 | 
Sidon sie etilacmatenineteoid 
32: module 2 | a | 
cc catiteaioncai anes tiem inal atric 
| module n-1 | module n | 


Fa a a a a ee 


90 Hexadecimal 90 indicates this is a Library 
Module Block. 


size Number of bytes in this block. 

module name Name of this module. 

msize Number of bytes of code in this module. 
caddr Disk address of module. 

taddr If non-zero, is the disk address of the text 


block. If zero, there is no text block. 


tsize Size of text block. 

module count Number of other modules that this module 
references. 

module 1 Number of the first module referenced. 

module 2 Number of the second module referenced. 


Numbers of other modules referenced. 


module n Number of the last module referenced. 
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4.4.3.15 #91 


byte --> 0 
4 
12 
14 

91 

size 

link name 

module 

address 

4.4.3.16 #92 

byte --> 0 
va 
12 
16 
20 
24 

92 

size 


- Library Entry Block 


| 91 | size (3 bytes) | 

[ao 2 

| link name | 

| (8 bytes) | 

| module | 

| address (4 bytes) | 
Hexadecimal 91 indicates that this is a library entry 
block 
Number of bytes in this block 
Blank-padded ASCII linker name of this entry point 
Number of the module in which this entry appears 
Address within this module of this entry point 

- Unit Block 


| . 92 | size (3 bytes) | 


| unit name 
| (8 bytes) 


| caddr (4 bytes) 
| taddr (4 bytes) 
| tsize (4 bytes) 
| gsize (4 bytes) 


Hexadecimal 92 indicates 
Block. 


that this is a Unit 


Number of bytes in this block - always OOOIC. 
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unit name 
caddr 
taddr 
tsize 


gsize 


4.4.3.17 #93 


byte --> 0 


10 


93 


size 
area number 
ref l 


ref 2 


ref n 


Name of this unit. 

Disk address of module. 
Disk address of text block. 
Size of text block. 


Number of bytes of globals in this unit. 


- FORTRAN Executable Data Area Reference Block 


| 93 | size (3 bytes) | 
| area number |......... 
fs orereeesntniioceneenenitnentoney 
| ref 1 (4 bytes) | 
| ref 2 (4 bytes) | 
[canbiciseicaetoreicrerenerasiiiniia 


| % ee | 
p= 


| each reference consumes 4 bytes | 


| ref n (4 bytes) | 
Hexadecimal 93 indicates this is a FORTRAN 
Executable Data Area Reference Block. 
Number of bytes in this block. 
Data area number. 
Address of first reference. 
Address of second reference. 
Addresses of other references. 


Address of last reference. 
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4.4.3.18 #94 - FORTRAN Executable Data Area Initialization Block 


byte --> 0o| 94 | size (3 bytes) | 
[a 

4 | data area number| ......... 
mennmenensanaael enna 

6 | | daddr (4 bytes) | 


10 | initialization data ....... | 


94 Hexadecimal 94 indicates this is a FORTRAN 
Executable Data Area Initialization Block. 


size Number of bytes in this block. 
data area numberNumber of the FORTRAN Data Area. 
daddr Starting address for this data. 


initialization data 
The data to fill the block with. 


00 If the size of the initialization data is an odd 


number of bytes, a filler of 00 is appended to 
make it an even number of bytes. 
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4.4.3.19 Text Block 


byte --> O | Textual data ............. | 


The format of a text block is operating system dependent. The current 
version uses the UCSD text file format, excluding the two initial header 


blocks. 


A text block is always stored aligned on a disk block boundary. 


4.4.3.20 EOF Mark 


byte --> Of} 00 | oo | 
| ie | 


An EOF (end of file) mark is indicated by a block containing two bytes of 
zero. 
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4.4.4 EXECUTABLE BLOCK DETAILS 


This section describes the layout of an executable block. It includes 
details of the jump table and segment tables. 


4.4.4.1 Layout of an Executable Block 


bytes --> O| 8F | size (3 bytes) | 

sir cidehieeenoa aemeeseesmnanienstaced 

4 | Jump Table Address (4 bytes) | 

8 | Jump Table Size (4 bytes) | 
t--——__——_____— 

12 | Data Size (4 bytes) | 

16 | Num | 00 | 00 | 

20 | oo | oo | 00 | oo | 

24 | Size 1 (4 bytes) | 


28 | Size 2 (4 bytes) | 


20+4%*n | Size n (4 bytes) | 
fatanorinusiukenmrnbscene se mmelasdeaass 


24+4*n | Jump Table (... size-1 bytes) ... | 
a ee 


8F Hexadecimal 8F indicates this is an Executable 
Block Definition. 


size Number of bytes in this block. 


jump table address 
Absolute load address of jump table. 


jump table size Number of bytes in the jump table. 


data size Total number of bytes in global common data 
areas. 
num Number of FORTRAN Data Areas. 
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00 00 00 00 00 00 
| six bytes of zero filler. 


size 1 Size of first FORTRAN Data Area. 

ities 2 Size of second FORTRAN Data Area. 
Sizes of other FORTRAN Data Areas. 

size n Size of last FORTRAN Data Area. 


jump table The jump table itself, including the executable 
code for the loader. 


If any FORTRAN Executable Data Area Initialization Blocks are present, 
they must immediately follow the executable block. 
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4.4.4.2 Format of the Jump Table 


A4 --> SSTOP | Number of Segments (2 bytes) | 
+2 | Main Segment Table (32 bytes) | 

+34 | Segment Table #2 (32 bytes) | 

| Sesient Table dn (32 Bytes) | 
24+n*32 | Dummy Table #n+1 (4 bytes) | 
| § START Descriptor (10 bytes) | 

| Segment #1 P#2 Descriptor | 


| Segment #1 Pin Descriptor | 


| Segment #2 P#1 Descriptor | All segment 
| a ee eee | descriptors 
| Segment #2 P#n Descriptor | are 10 bytes. 


| Segment #3 P#1 Descriptor | 


| Seg. #m P#n Descriptor (10 bytes) | 
-20 | Address pf REMOVE1 (4 bytes) | 
Piacente 


-16 | Address of Buffer (4 bytes) | 


-12 | Address of Code File (4 bytes) | 

seas ceiestsDe nn ON 

-8 | Active Segment List (4 bytes) | 

-4 7 Address of SSTOP (4 bytes) | 
btehinecmemsitonnecertmenneneieaerveminte a 

SSLOADIT | Object-code necessary to | 


| load and execute a segment. | 
Lh 
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4.4.4.3 Layout of a Segment Table 


A Segment Table consists of eight 32-bit values: 


byte --> 


Ce gy en ee ee ee 
0 | Address of first descriptor | 


4 | File Address of Segment | 
Bivens Oeie acs teeine Seen 


8 | Size of code in bytes | 
ie saeco eee eae 
12 Actual Address in Memory | 
16 | Scratch Return Address | 
ite ea iti ieee cnaneseeetro 

20 | Segment Reference Count | 
SSS SSS 

24 | Active Segment-list link | 


28 | oe Reserved ee | 
a Rage 


4.5 LOAD MODULE FILE FORMAT 


Binary files contain 1-byte markers that describe the record following it. 
The following are defined for the Computer System binary files created by 
the ALINK program or the SAVE command: 


16 (hex) 
03. 


02 


Transfer Address Marker. The next 4 bytes are the file's 
transfer address. | 


Data Block Marker. The following 4 bytes are the address of 
this block, followed by 2 bytes containing the block length. 


Data Block Marker. The following 4 bytes are the address of 
this block, followed by 1 byte containing the block length. 
Note: This marker was used in creating binary files under the 
1.0 operating system. It is supported as read only under the 
1.1 operating system. 
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5.0 DEBUG 


9.1 INTRODUCTION 


Debug is a debugging utility designed to run in the multitasking 
environment of CS-OS. 


59.2 INITIAL SETUP 


The DEBUG program is shipped with your system in relocatable format under 
the name DEBUG.OBJ. It is necessary for you to determine a memory 
location for running DEBUG and then to locate DEBUG at that address as a 
binary file. 


To determine the desired location, start the system and issue SYSMAP, 
which will display addresses of the system. Pick a location that will be 
outside the program(s) you want to test and still have room for DEBUG 
(1C00 hex bytes long). Then execute ALINK to locate it at that location. 


You now will have a version of DEBUG called DEBUG.BIN which will operate 
in an unused part of memory in your machine. 


5.3 OPERATING DEBUG 


First LOAD the program to be debugged, then type DEBUG. 


To begin testing a program, the programmer sets breakpoints (optional) and 
uses the GO command to jump execution to the first statement of the 
program (usually the address at which the program was located). 


To terminate the debugging (after the program releases any resources it 
may have acquired), the programmer places a breakpoint where the program 
terminates itself. When this breakpoint is hit, the E command is used to 
leave the debugging process. If any channel other than the E command is 
used to return to the system, performance becomes unpredictable and 
hangups may occur. 
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Debugging Modular Software 


There is a fundamental problem in debugging a program consisting of 
modules that have been linked after being assembled independently. While 
the assembler listing for each module displays relocatable addresses 
relative to zero, the user must do some arithmetic to locate an address or 
label within a riodule after it has been linked into a larger program. 
This procedure is not only inconvenient but time-consuming and vulnerable 
to error as well. 


Relocation Registers 


Debug contains a set of eight additional registers not found in the 
computer hardware. These are the eight relocation registers, implemented 
in software. The relocation registers are displayed, set and changed in 
the same manner as the address (A) and data (D) registers. 


Although in certain cases the relocation registers may be legally used in 
place of hex values, their primary purpose is to aid in converting the 
zero-based addresses of assembler listings to the absolute run-time 
addresses needed to debug software. 


A relocation register, say Rl, and the PC could be set to the base address 
of the program module to be tested. These addresses alone suffice for the 
debugging of a single-module program. Any relative address in the module 
can be translated to an absolute address with the command 


<relative address> Rl 


9.3.1 EXAMPLE OF SETTING UP DEBUG FOR A MULTIPLE-MODULE 
PROGRAM 


For purpose of this example consider a software package consisting of 
three modules: MOD1, MOD2, and MOD3. Assume that this software does not 
work, so needs debugging. Use the linker (ALINK) to link together the 
MOD1, MOD2 and MOD3. Note: In order to avoid confusion it is recommended 
that the user adopt a convention in naming debug modules. A suggestion is 
to name the linker output with the original module's name plus an appended 
letter (e.g.'"D"). 


save the LINK map, which in this example looks like the following: 
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MOD1 10E00 

MOD2 1124E 

MOD3 118EC 
Bring up the debugger by typing 


DEBUG <parameters for program under test> 


To set R1, R2, and R3 to MOD1, MOD2, and MOD3 respectively, type 


R1 10E00 
R2 1124E 
R3 118EC 


where the values have been obtained from the LINK map. 
In order to access a value in any module, simply type in the relative 
address found on the assembly listing and then the number of the 


relocation register (e.g., R2) containing the base address of the module. 
The address for debugging will then be computed for you. 


59.4 DEBUG COMMANDS -- SYNTAX AND DEFINITIONS 


The syntax notation used with DEBUG is: 
CM EXP 


CM iS a command that directs the next action of DEBUG. Section 5.5 
contains a list of commands. 


EXP is a numeric expression which consists of numbers, relocation 
registers, and qualifiers. An EXP ultimately reduces to a single numeric 
value, or number. 


Numeric expressions (EXP) are of the following form: 


VAL 32 bit value 
VAL.B 8 bit value 
VAL.W 16 bit value 
VAL. L 32 bit value 


The optional two-character extension to the value (.B,.W,.L) is a length 
modifier which masks the value as indicated. 
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VAL is a value of the form: 


NUM number value 

R# | relocation register value), 

NUM R# number plus relocation register value 
NUM+R# _ tf ‘t '! 1! tt 


NUM is a number of the forms: 


hex hex number (default) 
Shex hex number 

_ shex negative hex number 
-Shex negative hex number 
&dec decimal number 
-&dec negative decimal number 


5.4.1 EXPRESSION EXAMPLES 


The following table shows examples of typical expression usage, and the 
Hex and decimal values of the expression. (NOTE: assume R3 contains 20000 
hex. ) 


EXPRESSION HEX VALUE DECIMAL VALUE 


8EFC3 8EFC3 585667 
$8EFC3 8EFC3 585667 
&25R3.W 19 25 
SFFE2.L | FFFFOO1E -65506 
-1.B FF 255 
10+R3 20010 | 131088 


The HEX VALUE is unsigned 32 bit. The DECIMAL VALUE is signed 32 bit. 
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9.5 SUMMARY OF DEBUG COMMANDS 


Command 


A/f: exp 
A/f exp 


BR exp 
BR -exp 


BR CLEAR 


PC exp 


SS exp 


SR exp 


R# exp 


US exp 


exp 


Description 


Displays contents of all address registers 
Displays and prompts for change of all address 
registers 

Displays contents of an address register 

Displays and prompts for change of an address 
register 

sets an address register to hexexp 

Displays all breakpoints set 

sets a breakpoint at address exp 

Removes a breakpoint at address exp 

Clears all breakpoints set 

Displays contents of all data registers 

Displays and prompts for change on all data registers 
Displays contents of a data register 

Displays and prompts for change of a data register 
Sets a data register to exp 

Displays all registers 

Displays memory at starting address. Returns to system 
Displays memory between two addresses. If second 
hexexp < first hexexp, then displays second-hexexp 
bytes starting at first hexexp. 

Begins execution at address contained in PC 

Begins execution at address exp 

Changes memory starting at exp 

Displays contents of PC 

Displays and prompts for change of PC 

sets PC to exp 

Displays contents of system stack 

Displays and prompts for change in system stack 
Sets system stack to exp 

Displays contents of status register 

Displays and prompts for change in status register 
sets status register to exp 

Displays contents of all relocation registers 
Displays and prompts for change of all relocation 
registers 

Displays a relocation register 

Displays and prompts for change of relocation register 
Sets relocation register to exp 

Traces single instruction execution 

Displays contents of user stack 

Displays and prompts for change of user stack 

sets user stack to exp 
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9.6 REGISTER DISPLAY 


Register commands 
along 


registers, 


counter registers. 


5.6.1 


Command 


DR 
PC=00010842 


DO=00000000 
D4=00000000 


A0=00000000 
A4=00000000 


RO=00040000 
R4=00000000 


D6 
D6=00000000 


D6 6 


D6 
D6=00000006 


D: 

DO=00000000 
D1=00000001 
D2=00000002 


D3=00000003 7 


D4=00000004 
D5=00000005 
D6=00000006 
D7=00000000 


REGISTER 


SR=2700 


D1=00000001 
D5=00000000 


A1=00000000 
A5=00000000 


R1=00041B42 
R5=00000000 


25 


27 


Description 


Display al 
SS=00010406 


D2=00000002 
D6=00000000 


A2=00000000 
A6=00000000 


R2=00000000 
R6=00000000 


Display regi 


Change contents of D6 to 6 


Display D6 


DISPLAY EXAMPLES 


1 registers 
US=0000CD8C 


D3=00000000 
D7=00000000 


A3=00000000 
A7=00010406 


R3=00000000 
R7=00000000 


ster D6 


user stack, 


status, 


are used to display or change address, data, relocation 
with system stack, 


and program 


Prompt for change of all data registers 


Don't change 
Don't change 
Don't change 
Change D3 to 
Change D4& to 
Change D5 to 
Don't change 
Change D7 to 


DO 

D1 
D200000066 
3 

4G 

5 
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D Display all data registers 
DO=00000000 D1=00000001 D2=00000002 D3=00000003 
D4=00000004 D5=00000005 D6é=00000006 D7=00000007 


SS Display system stack 
55=00010406 


US Display user stack 
US=0000CD8C 


US: Change user stack 
US : OOOOCD8C? E000 


US Display user stack 
US=0000E000 


SR Display status register 
SR=2700 
R Display relocation registers 


RO=00040000 R1=00041B42 R2=00000000 R3=00000000 
R4=00000000 R5=00000000 R6=00000000 R7=00000000 


PC R1 set PC to relocation register 


PC Display PC 
PC=00041B42 


AO Display address register ad 
A0=00000000 


AO 1000+R1 Change AO 
AO Display AO 


A0=00042B42 


D2 Display D2 
D2=00000002 
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D2 -1 Change D2 to -1 Hex 


D2 Display D2 
D2=FFFFFFFF 


D2 -1 W Change D2 to -1 hex, word length 


D2 Display D2 
D2=O000FFFF 


D Display data registers 
DO=00000000 D1=00000001 D2=O0000FFFF D3=00000003 
D4=00000004 D5=00000005 D6=00000000 D7=00010406 


A Display address registers 
A0=00042B42 A1=00000000 A2=00000000 A3=00000000 
A4=00000000 A5=00000000 A6=00000000 A7=00010406 


59./ MEMORY DISPLAY 


The DM command displays memory bytes in both hexadecimal and ASCII. 


Format Description 

DM start Displays 16 bytes of memory beginning at start 
. address. 

DM start end Displays memory bytes from start address to 


end address; end must be greater than or 
equal to start. 


DM start count Displays ‘count’ bytes beginning at start address; 
‘count’ must be less than start. 


NOTE: 'start', 'end', and 'count' are all numeric expressions. 


All displays are done in 16-byte units, with the number of bytes displayed 
rounded to the next highest multiple of 16. 


Pressing Ctrl-Break on the keyboard will terminate the display. 
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9./.1 MEMORY DISPLAY EXAMPLES 


Command 


DM 10000 
010000 4E F9 


DM10000 10020 
010000 4E F9 
010010 4A FC 
010020 4A FC 


DM 10000 20 

010000 4E F9 
010010 4A FC 
010020 4A FC 


5.8 MEMORY 


00 


00 
4A 
4A 


00 
4A 
4A 


CHANGE 


O1 


O1 
FC 
FC 


O1 
FC 
FC 


08 


08 
4A 
4A 


08 
4A 
4A 


Description 


Display memory at 10000 Hex 
30 4A FC GA FC GA FC GA FC 4A FC N....0J.5.J.5.J. 


Display 10000 to 10020 Hex 


30 4A FC 4A FC 4A FC 4A FC 4A FC N....OJ.J.J.5.J5 
FC 4A FC 4A FC 4A FC GA FC GA FC J.JS.J.J.5.5.5.g 
FC 4A FC 4A FC 4A FC 4A FC 4A FC J.J.J.5.3.5.5.I 


Display 20 hex bytes starting at 10000 hex 


30 4A FC 4A FC GA FC 4A FC 4A FOCN....0J.53.J5.J5.J. 
FC 4A FC 4A FC 4A FC 4A FC 4A FC J.J.J.5.5.5.5. 5 
FC 4A FC 4A FC 4A FC 4A FC 4A FC J.J.J.J.J.J5.J. 


The OP command can be used to display or change memory a byte at a time. 


Format 


OP exp 


Description 


Opens memory at address specified in exp. 
Enters the open subcommand mode. 


5.8.1 OPEN SUBCOMMAND MODE 


In the open subcommand mode, the address contained in exp when the OP 
command was entered is displayed, as well as the value at that address. 
Then a prompt is issued for a response. A response consists of either a 
location control character or a numeric expression. 
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Format Description 


exp <loc ctrl char> Set the value of the address to [hexexp] if 
desired. Use the location control character 
to determine what location to process next. 


Location control characters: 


exp <CR> Set the value at the address to exp, then go 
to next address. <CR> is carriage return. 


<CR> Go to next address 
=<CR> | Stay at current address 
<CR> Go to previous address 
. <CR> Without [hexexp], terminate subcommand mode 


59.8.2 MEMORY CHANGE EXAMPLES 


Command Description 

OP 1000 Begin memory change at 10000 hex 

010000 4E ? Don't change, go to next address 

010001 F9 ? | Don't change, go to next address 

010002 00 ? Don't change, go to previous address 
010001 F9 7&64 Change location to 64 decimal go to next 
010002 00 ? : Don't change, go to previous address 
010001 40 ? Notice change to 40 hex (64 dec), go to next 
010002 00 ? Go to next 

010002 O01 ?= Stay at same address 

010003 O01 ?= This is useful for 

010003 O1 ?= Polling an I/O to next address 

010003 01 ?= Location 

010003 O1 ? Go to next 

010002 O1 ? FE8A Change to FE8A Hex 

VALUE TOO BIG Can't enter a word into a byte 

010004 08 ? FE8A.B Specify byte length 

010005 30 ? Backup 

010004 8A ? Verify lower byte of word 

010005 30 ?. - Terminate the open subcommand mode 
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9.9 EXECUTION CONTROL 


Format Description 

BR Displays all breakpoints 

BR exp sets breakpoint at exp 

BR -exp Removes a breakpoint from exp 

BR CLEAR Clears all breakpoints 

E Returns control to system 

G Begins execution at address in PC 

G exp Begins execution at exp 

T Traces the execution of one instruction. 


9.9.1 EXAMPLES OF EXECUTION CONTROL 


Command Description 

BR Display Breakpoints 
Breakpoint(s)= None is set 

RO 10000 , Examine relocation register 
BR RO Set breakpoint at RO 

BR 


Breakpoint(s): 010000 Display breakpoints 
G ORO Begin program execution at 10000 hex 


Breakpoint hit 
PC=00010000 SR=2000 SS=0000CD8C US=0000CD8C 
DO=00000000 D1=00000000 D2=00000000 D3=00000000 
D4=00000000 D5=00000000 D6=00000000 D7=00000000 
AO=00000000 A1=00000000 A2=00000000 A3=00000000 
A4=00000000 A5=00000000 A6=00000000 A7=O0000CD8C 
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T 
PC=00010830 


SR=2000 


Trace one instruction 
SS=0000CD8C US=0000CD8C 


DO=00000000 
D4=00000000 


D1=00000000 
D5=00000000 


D2=00000000 D3=00000000 
D6=00000000 D7=00000000 


A0=00000000 
A4=00000000 


A1=00000000 
A5=00000000 


A2=00000000 A3=00000000 
A6=00000000 A7=0000CD8C 


BR -10000 


BR 


BREAKPOINT(S): 


BR 83A 


BR 83ARO 


BR 84A+RO 


BR 


BREAKPOINT (S): 


BR -83A 


BR 


BREAKPOINT(S): 


G 


PC=0001083A 


SR=2000 


Remove breakpoint at 10000 hex 


Display breakpoints 
None set 


Set breakpoint at 83A hex 
Set breakpoint at 1083A hex (83A+RO) 
Set breakpoint at 1084A hex 


Display breakpoints 
00083A 01083A 01084A 


Remove breakpoint (83A hex was a mistake) 


Display breakpoints 
01083A 01084A 


Continue program execution at PC 


Breakpoint hit 
SS=0000CD86 US=0000CD8C 


DO=00000000 
D4=00000000 


D1=00000000 
D5=00000000 


D2=00000000 D3=00000000 
D6=00000000 D7=00000000 


mm Op ab aw > =D aS GE Ot an GE we mn nD oD aw GH ae Gm» ow gy a cE ee &> a Se em aD oe @ GR oH ah a mm am am GF ar Gp a= ae ww ae ae ow = am om ae ae ae =P «om an 


A0=00000000 
A4=00000000 


T 
PC=0001083E 


A1=00000000 
A5=00000000 


SR2000 


A2=00000000 A3=00000000 
A6=00000000 A7=0000CD86 


Trace one instruction 
SS=00010406 US=0O000CD8C 


DO=00000000 
D4=00000000 


D1=00000000 
D5=00000000 


D2=00000000 D3=00000000 
D6=00000000 D7=00000000 


AO0=00000000 
A4=00000000 


A1=00000000 
A5=00000000 


A2=00000000 A3=00000000 
A6=00000000 A7=00010406 
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G Continue program execution at PC 
PC=0001084A SR=2708 55=00010406 US=0000CD8C 
DO=00000000 D1=00000000 D2=00000000 D3=00000000 
D4=00000000 D5=00000000 D6=00000000 D7=00000000 
A0=00000000 A1=00000000 A2=00000000 A3=00000000 
A4=00000000 A5=00000000 A6=00000000 A7=00010406 


BR Display breakpoints 
BREAKPOINT(S): 01083A 01084A 

BR CL Clear all breakpoints 
BR Display breakpoints 
BREAKPOINT(S) : 

E Exit debug 


9.9.2 HARD COPY 


The following commands echo CS-Debug commands to the line printer, thus 
providing a convenient record of a debugging session. 


Format Description 
LPT ON Issues a form feed and begins to send 


a copy of debug session to line printer. 


LPT OFF Stops sending to line printer. 
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A.O APPENDIX: ERROR MESSAGES AND CODES 


A.1 ERROR MESSAGES FROM OPERATING SYSTEM COMMANDS 


The following messages are those that occur most frequently. For a 
complete list of errors related to a command, see the command description 


in Chapter 1. 
General Messages 


COMMAND FORMAT ERROR 
UPPER CASE REQUIRED 

CHECK SPELLING OF COMMAND 
OR PROGRAM NAME 


Messages used by many commands. 


SYNTAX ERROR 


BAD PARAMETER 


Data entered cannot be 
processed as a command. 


Command must be entered in 
uppercase. 


Command not found. 


The command line does not 
conform to the syntax 
specified for the command. 


A bad argument in the command 
line was encountered. 


The following messages may occur during program loading -- 


LOAD ADDRESS TOO LOW 


NOT ENOUGH MEMORY FOR LOAD 


INVALID LOAD FILE FORMAT 


Starting address must_ be 
above APPBEGIN. 


Ending address must be below. 


File type must be binary, type 
00 or O1. 


The next two error messages result from use of the RENAME command: 


DUPLICATE NAME 


Indicates that the new name 
already exists on the disk. 
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FILE PROTECTED Indicates that the old file is 


protected from renaming 
(access code = 02, 03, 06, or 
07). 


The next error message is from the SET command 


ILLEGAL VALUE | Value entered is unreasonabl 
for the type of command 


(D 


The next 3 messages come from the RUNTASK command: 


NO TRANSFER ADDRESS The binary load module 


specified in the RUNTASK 
command does not have a 
transfer address. 


NO MORE TASKS MAY BE STARTED There is no PCB available to 
start a task with the run 
command. All PCBs are in use. 


DUPLICATE TASK NAME There is already a PCB with 
the name specified in the 
RUNTASK command. 


The next 3 messages are related to commands involving tasks (i.e., 
PRIority, DELAY WAKEUP, RUNTASK, KILL, DELAY, RESUME, SHOW) 


NO SUCH TASK There is no PCB with a task 
name that matches the one 
entered. 

INVALID PRIORITY A priority outside the range 


1-27 was used in a RUNTASK or 
PRIORITY command. 


SYSTEM TASK CANNOT BE KILLED You cannot issue the KILL 
| command for the system task. 


The next two messages come from the SAVE command: 


INVALID TRANSFER ADDRESS Transfer address must be 
between the start address and 
end address and be on an even 
boundary. 


ENDING ADDRESS IS TOO LOW OR TOO HIGH Ending address must be between 
starting address and end of 
system memory. 
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The next two messages come from the SECURE command: 


DIR.DIR FILE ACCESS CANNOT BE CHANGED DIR.DIR is the directory file 
on the disk. Its access code 
is not to be changed. 


VALUE RANGE ERROR Access code specified is not 
acceptable. 


The next two messagers come from the SUBMIT command: 


SUBMIT FILE ERROR An error occurred while 
trying to open the requested 
SUBMIT file or a command line 
exceeded 80 characters. 


WRONG FILE TYPE A submit file must be text or 
type 3. 


File-dependent messages 


WRITE TO OLD-STRUCTURED FILE 
FILE ALREADY OPEN FOR WRITE 
FILE NOT FOUND 

ILLEGAL FILE ACCESS METHOD 
INVALID FILENAME 

READ BEYOND END OF FILE 
BUFFER SIZE INCORRECT 

FILE NOT EXTENDABLE 

DISK FULL 

WRITING TO READY-ONLY FILE 
WRONG FILE TYPE FOR ACCESS 
INVALID SECTOR SPECIFIED 
FILE PROTECTED 

NEW FILE BEING READ 

BAD FILE -- SYSTEM ERROR 

NO SPACE FOR CONTIGUOUS FILE 
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A.2 COMMON DEVICE AND MANAGER ERROR CODES 


A.2.1 MESSAGE FORMAT 


The Syntax for messages is: 
component [ERROR=SNNNN] [message text] [TASK=taskname ] 


COMPONENT is the name of a device or operating system manager issuing the 
message. 


ERROR=SNNNN is a four digit hexadecimal error code which identifies the 


error. Driver programs issue error codes in the range SO001 
through SOOFE. Manager programs issue the remaining error 
codes. It is possible for a device driver to issue a manager 


error return code. You can find the reason for this code by 
looking through the manager error codes section. 


This field of the message display is always printed if no 
message text is available. If message text is available then 
this field is printed only if you have SET EC=YES. 


MESSAGE TEXT is supplied by device drivers and system managers for many of 
the error codes listed in this section. Message text is printed 


with the message, if it is available. 


TASK=TASKNAME is printed with the error message for all tasks other than 
the SYSTEM task. 
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A.2.2 COMMON DEVICE-DRIVER ERROR CODES 


SOO001 reserved 

$0002 reserved 

$0003 reserved 

$0004 NO CONTROL BLOCK STORAGE 

$0005 READ/WRITE ERROR 

$0006 INVALID DATA TRANSFER DIRECTION IN DIB 

$0007 ILLEGAL BUFFER ADDRESS IN DTCB 

$0008 END OF FILE 

SO0009 RECORD LARGER THAN BUFFER; TRUNCATED - input record too big 
SOOOA DEVICE NOT READY 

SOOOB NON-ZERO BYTE I/O WRITE STATUS - buffer full 
SO00C NON-ZERO BYTE I/O READ STATUS - buffer empty 
SOOOD SYSIO REQUEST CANCELLED 

SOOOE INVALID FUNCTION PACKET CODE AT OFFSET SNNNN 
SOOOF INVALID TRANSFER MODE IN DIB 


$0021 INVALID VALUE FOR SETTRANS FUNCTION PACKET 

$0022-SO05F have a common meaning for function packet data errors in 
all drivers. The error code is equal to the function code 
number plus $0020. The message produced by the system is 
as follows: 


ERROR=SNNNN INVALID DATA IN FUNCTION $NNNN AT OFFSET 
SNNNN. 


$0060 CANNOT READ - DIBDTD SPECIFIED OUTPUT 
$0061 CANCEL FAILED 

$0062 READ NOT SUPPORTED - by device driver 
$0063 WRITE NOT SUPPORTED - by device driver 
$0064 FUNCTION NOT SUPPORTED - by device driver 
$0065 BWRITE NOT SUPPORTED - by device driver 
$0066 BREAD NOT SUPPORTED - by device driver 
$0067 CANNOT WRITE - DIBDTD SPECIFIED INPUT 
$0068 TSTBYTE NOT SUPPORTED - by device driver 
$0069 DTACHDVR NOT SUPPORTED - by device driver 
$006A ATACHDEV NOT SUPPORTED - by device driver 
SOO6B DTACHDEV NOT SUPPORTED - by device driver 
SOO6C reserved 

SOO06D reserved 

SOO6E reserved 

SOO6F reserved 
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A.2.3 MANAGER ERROR CODES 


RTMMGR ERROR CODE 


$2000 


RTMMGR ERROR 


SEMAPHORE ERROR CODES 


$3001 
$3002 
$3003 
$3004 
$3005 
$3006 
$3007 
$3008 
$3009 
$300A 
$300B 
$300C 
$300D 
$300E 
$300F 
$3010 
$3010 


DUPLICATE SEMAPHORE NAME 

ALL SEMAPHORES IN USE 

ILLEGAL MAXIMUM COUNT 

COUNT EXCEEDS MAXIMUM COUNT - will be truncated 
ILLEGAL QUEUING MODE 

ILLEGAL SEMAPHORE NAME OR SYSTEM I[.D. 

NOT OWNER TASK - cannot detach semaphore 
REQUESTED COUNT EXCEEDS MAXIMUM COUNT 
INSUFFICIENT SYSTEM SPACE TO QUEUE REQUEST 
SEMAPHORE HAS BEEN DETACHED - request terminated 
INVALID COUNT 

SEMAPHORE NOT FOUND 

INVALID TIME OUT VALUE 

REQUEST TIMED OUT 

FUNCTION NOT SUPPORTED 

INITIAL COUNT EXCEEDS MAXIMUM COUNT - will be truncated 
REQUEST CANCELLED 


MEMORY MANAGEMENT ERROR CODES 


$6001 
$6002 
$6003 
$6004 
$6005 
$6006 
$6007 
$6008 
$6009 
S600A 
S600B 
$600C 
$600D 
S600E 


INVALID NAME IN MPD 

DUPLICATE MEMORY POOL NAME 

NO AVAILABLE FPD BLOCKS - internal storage 

ILLEGAL NAME - passed as function argument 

MEMORY POOL NOT FOUND 

POOL STILL CONTAINS MEMORY - descriptor cannot be removed 
ILLEGAL SUB POOL SIZE - must be greater than zero 

ILLEGAL SUB POOL BOUNDARY - memory must be aligned on page boundary 
SUB POOL OVERLAP - memory overlaps existing sub pool 

SUB POOL OVERLAPS SYSTEM AREA 

NO AVAILABLE SPD BLOCKS - internal storage 

SUB POOL MEMORY NOT FOUND 

ILLEGAL DMA MEMORY REQUEST - greater than 64K 

reserved | 


S600F FUNCTION NOT SUPPORTED 


$6010 
$6011 
$6012 


MEMORY NOT AVAILABLE - see Appendix F "System Memory Consumption" 
reserved 
MEMORY CANNOT BE RETURNED 
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I/O MANAGER ERROR CODES 


$8100 DUPLICATE VOLUME IDENTIFIER 

$8200 INVALID SYSIO CALL 

$8300 LOGICAL UNIT NOT OPENED. 

$8400 NO CONTROL BLOCK STORAGE - inadequate system space, 
see Appendix F " System Memory Consumption" 

$8500 DUPLICATE LOGICAL UNIT 

$8600 DEVICE NOT FOUND 

$8700 NOT DEVICE OWNER 

$8800 NON SHARABLE DEVICE ALREADY OPEN 

$8900 BYTE I/O NOT SUPPORTED 

S8A00 PROCESSING I/O REQUEST ALREADY 

S8BO0 NOT OPENED FOR BYTE I/O 

S$8C00 INVALID DIB FIELD (TRN, DTD, or RSO) 

S8D00 EVENT NOT FOUND 

S8EOO EVENT NOT OPENED 

S8F00 ILLEGAL READ BUFFER ADDRESS 

$9000 CONTROL BLOCK NOT WORD-ALIGNED 

$9100 CONTROL BLOCK OR BUFFER OUT OF RANGE 


A.2.4 CODES FOR ASYCHRONOUS REQUESTS 


SYSIO will return a -1 in register D7.W if the asynchronous operation 
has started successfully. Completion status is returned in the 
DICSTA field of the Data Transfer Control Block. The convention is 
the same as for register D7 status. A -1 indicates that the 
operation is not yet complete; a zero indicates complete with no 
error; and a positive number indicates completion with an error. 
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A.3.1 


$0021-$0041 


A.3 DRIVER ERROR CODES 


CRT GRAPHICS DRIVER (#GR) ERROR CODES 


Data out of limits for a function packet 
Function number = error number - $0020 


A.3.2 CRT DISPLAY DRIVER (#SCRN, #CNSL) ERROR CODES 


SOOOE INVALID FUNCTION PACKET CODE AT OFFSET SNNNN 
$0015 MAXIMUM NUMBER OF WINDOWS OPENED 

$0016 ADDRESS BOUNDARY ERROR - OPEN FAIL 

$0021 DATA OUT OF LIMITS FOR A FUNCTION PACKET 
through (Function number = error number - $0020) 
SOO4B 

$0069 DTACHDRV NOT SUPPORTED 

SOO6A ATTACHDEV NOT SUPPORTED 

SOO6B DTACHDEV NOT SUPPORTED 


A.3.3 KEYBOARD (#CON) ERROR CODES 


$0009 - RECORD LARGER THAN BUFFER; TRUNCATED 

SOO00C NON-ZERO BYTE I/O READ STATUS 

SOO00OD REQUEST CANCELLED | 

SOOOE INVALID FUNCTION PACKET CODE AT OFFSET SNNNN 
$0010 KEYBOARD FUNCTION KEY EXCEPTION 

$0021 BAD DATA IN SET TRANSFER MODE FUNCTION PACKET 
S002B INVALID TAB AMOUNT 

$002D COMMAND PARSING NOT ENABLED 

$0063 WRITE. NOT SUPPORTED 

$0065 BWRITE NOT SUPPORTED 

SO06A ATCHDEV NOT SUPPORTED 

SOO6B DTACHDEV NOT SUPPORTED 
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$0009 
$000C 
$000D 
SO00E 
$0011 
$0012 
$0013 
$0014 
$0015 
$0016 
$0017 
$0018 
$0019 
SOO1E 
SOO1F 
$0021 
$0024 
$0026 
$0027 
$002E 
$002F 
$0031 
$0032 
$0035 
$0063 
50065 
SO06A 
SO06B 


$0006 
$0009 
SOO0A 
SOOOB 
$000D 
SOOOE 
SOOOF 
$0010 
$0012 
$0014 
$0019 


A.3.4 KEYPAD (#KPD) ERROR CODES 


RECORD LARGER THAN BUFFER; TRUNCATED 
NON-ZERO BYTE I/O READ STATUS 

REQUEST CANCELLED 

INVALID FUNCTION PACKET CODE AT OFFSET SNNNN 
(FPKT 12, 19) SCANCODE ALREADY IN TABLE 
(FPKT 12, 19) NOT ENOUGH SPACE IN TABLE 
(FPKT 13) ERROR IN TABLE STRUCTURE 

(FPKT 13) SCANCODE NOT FOUND IN TABLE 

(FPKT 12, 19, 13) INVALID TABLE NUMBER 

(FPKT 12) ILLOGICAL SCANCODE FOR TABLE 

(FPKT 12) STRING LENGTH <GT> 20 

(FPKT 12, 19) BAD TERMINATOR, NOT SOD OR $04 
(FPKT 12, 19) INVALID BUFFER CODE 

(FPKT 17) TABLES NOT EMPTY, CAN'T REALLOCATE 
(FPKT 17) NOT ENOUGH MEMORY FOR TABLES 

(FPKT 01} DIBTRN MODE NOT O OR 1 

(FPKT 03) BAD TIME VALUE (MINUS OR >256) 
(FPKT 06) INVALID LED NUMBER 

(FPKT 07) INVALID LED NUMBER 

(FPKT 14) BAD TABLE ##, MUST BE 1-4 

(FPKT 15) INVALID BUFFER CODE 

(FPKT 17) REQUESTED TABLE SIZE NEGATIVE 
(FPKT 19) STRING TOO LONG OR BAD TERMINATOR 
(FPKT 21) INVALID ENTER/SHIFT KEY 

WRITE NOT SUPPORTED 

BWRITE NOT SUPPORTED 

ATCHDEV NOT SUPPORTED 

DTACHDEV NOT SUPPORTED 


A.3.5 PRINTER DRIVER (#PR) ERROR CODES 


INVALID DATA TRANSFER DIRECTION IN DIB 
RECORD LARGER THAN BUFFER; TRUNCATED 

DEVICE NOT READY 

NON-ZERO BYTE I/O - WRITE STATUS 

REQUEST CANCELLED 

INVALID FUNCTION PACKET CODE AT OFFSET SNNNN 
INVALID TRANSFER MODE IN DIB 

PRINTER DRIVER COLDSTART FAILED 

PARAMETER ERROR IN DTCB 

ONLY FIXED LENGTH TRANSFER ALLOWED IN GRAPHICS 
DETACH DRIVER FAILED 


$0021-$0045 DATA OUT OF LIMITS FOR A FUNCTION PACKET 


FUNCTION NUMBER = ERROR NUMBER 


$0061 


-$0020. 
CANCEL FAILED 
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A.3.f¢ 


$0020 
$0021 
$0022 
$0030 
$0031 


$0032 


$0033 
$0034 


$0020 
$0021 
$0022 
$0023 
$0024 
$0028 
$0030 
$0031 
$0032 
$0033 
$0034 
$0035 
$0040 
$0041 
$0042 
$0043 
$0044 


A.3.8 ITC 


$0006 
$0009 
$000D 
S000E 
S000F 
$0010 
$0011 
$0012 
$0015 


A.3.6 RS-232 (#SER) STATUS CODES 


DTCB BUFFER FULL BEFORE READ 

FCN CODE RETURNED ERROR 

INTMGR ERROR DURING DMA OPERATION 
DATA SUSPECT: PARITY ERROR DETECTED 
DATA SUSPECT: FRAMING ERROR DETECTED 


DATA LOST: CIRCULAR BUFFER OVERRUN 
DATA LOST: HARDWARE OVERRUN 
BREAK RECEIVED 


IEEE-488 (4#BUS) STATUS CODES 


CONTROLLER NOT ATTACHED 

CONTROLLER ALREADY ATTACHED 

DUPLICATE OR INVALID BUS ADDRESS 

ATTACH WOULD EXCEED MAXIMUM DEVICE COUNT 
DRIVER CANNOT DETACH: DEVICES ACTIVE 
FUNCTION CODE - RETURNED ERROR 

WRITE NOT STARTED: NOT ADDRESSED AS TALKER 
WRITE ABORTED: TIMEOUT ON DMA DATA WRITE 
WRITE ABORTED: ERROR DURING COMMAND SEQUENCE 
WRITE ABORTED: TIMEOUT ON DATA 

WRITE ABORTED: LOST TALKER STATE 

WRITE NOT STARTED: NULL RECORD 

READ NOT STARTED: NOT ADDRESSED AS LISTENER 
READ ABORTED: TIMEOUT ON DMA DATA READ 

READ ABORTED: ERROR DURING COMMAND SEQUENCE 
READ ABORTED: TIMEOUT ON DATA 

READ ABORTED: LOST LISTENER STATE 


(#1ITC) STATUS CODES 


INVALID DATA TRANSFER DIRECTION IN DIB 

RECORD LARGER THAN BUFFER; TRUNCATED 

REQUEST CANCELLED 

INVALID FUNCTION PACKET CODE AT OFFSET SNNNN 
INVALID TRANSFER MODE IN DIB 

DUPLICATE ITC IDENTIFIER 

INVALID ITC IDENTIFIER 

INVALID ATTACH/DETACH CODE 

LOWER TRIGGER BYTE EXCEEDS UPPER TRIGGER BYTE 
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$0016 
$0017 
$0018 
$0019 
$0021 
$0023 
$0062 
$0063 
$0065 
$0066 
$0068 
SOO6A 
SO06B 
$0070 
$0071 
$0072 
$0073 
$0075 
$0076 
$0077 
$0078 
$0079 
SOO7A 


$0005 
SOO0A 
SOOOB 
$000C 
S000D 
SOOOE 
SOOOF 
$0021 
$0023 
$0025 
$0027 
$0068 
SO06A 
S006B 


BUFFER OFFSET EXCEEDS BUFFER LENGTH 
EITHER BUFFER LENGTH OR OFFSET ILLEGAL 
NO AVAILABLE SYSTEM MEMORY 

RETURN OF SYSTEM MEMORY FAILED 

INVALID TRANSFER MODE 

INVALID TIME OUT PARAMETER 

READ NOT SUPPORTED 

WRITE NOT SUPPORTED 

BWRITE NOT SUPPORTED 

BREAD NOT SUPPORTED 

TSTBYTE NOT SUPPORTED 

ATACHDEV NOT SUPPORTED 

DTACHDEV NOT SUPPORTED 

WRITE WAIT FAILED 

READ WAIT FAILED 

READ SIGNAL FAILED 

WRITE SIGNAL FAILED 

REQUEST TIMED OUT 

CHANNEL(S) IN USE DRIVER WILL NOT BE DETACHED 
ERROR IN COLDSTART SEQUENCE 

ERROR IN DETACH SEQUENCE - DETACH INCOMPLETE 
DRIVER NOT ATTACHED 

DRIVER IS ATTACHED 


A.3.9 PARALLEL PORT (#PPU) DRIVER ERROR CODES 


READ ERROR - trying to read in printer output mode 
DEVICE NOT READY 

NON-ZERO BYTE I/O WRITE STATUS - buffer full 
NON-ZERO BYTE I/O READ STATUS - buffer empty 
REQUEST CANCELLED 

INVALID FUNCTION PACKET CODE AT OFFSET SNNNN 
INVALID TRANSFER MODE IN DIB 

INVALID VALUE FOR SET TRANSFER MODE DATA 

SET PARALLEL PORT MODE DATA INCORRECT 

SET TIMEOUT DATA INCORRECT 

SET AUTO LINEFEED DATA INCORRECT 

BTEST IS NOT SUPPORTED BY THIS DRIVER 
ATCHDEV NOT SUPPORTED 

DTACHDEV NOT SUPPORTED 


A.3.10 DISK (#FDOX OR #HDOX) ERROR CODES 


$0005 READ/WRITE ERROR 
S0006 INVALID DATA TRANSFER DIRECTION IN DIB 
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$0007 ILLEGAL BUFFER ADDRESS IN DTCB 

SOOOA DEVICE NOT READY | 
SOOOE INVALID FUNCTION PACKET CODE AT OFFSET SNNNN 
$0010 SEEK TRACK | 
$0011 LOGICAL SECTOR OR TRACK NUMBER TOO BIG $¥iddvede 
$0012 VOLUME CHANGED 

$0013 reserved 

$0014 I/O REQUEST TIMED OUT 

$0015 reserved 

$0016 ILLEGAL BUFFER ADDRESS 

$0017 DISK FORMAT NOT RECOGNIZED 

$0018 DISK WRITE PROTECTED 

$0019 SECTOR BUFFER TOO SMALL 

SOO1A WRITE FAULT SENET TET 

SOO1B CRC ERROR STE TET 

$001C SECTOR NOT FOUND S*vsvsvsdsucecs 

SOO02F TLLEGAL VOLUME IDENTIFIER 

$0061 CANCEL FAILED 

$0065 BWRITE NOT SUPPORTED 

$0066 BREAD NOT SUPPORTED 

$0067 CANNOT WRITE - DIBDTD SPECIFIED INPUT 
$0068 TSTBYT NOT SUPPORTED 

S006A ATCHDEV NOT SUPPORTED 

SO006B DTACHDEV NOT SUPPORTED 

$0070 DATA ADDRESS MARK NOT FOUND $*recsderedecs 
$0071 reserved | 

$0072 ABORTED COMMAND 

$0073 reserved 

$0074 reserved 

$0075 reserved 

$0076 UNCORRECTABLE DISK ERROR $vvevrdvedevers 
$0077 BAD SECTOR DETECTED $*evvsdveress 

$0078 HARD DISK CONTROLLER NOT PRESENT 


A.3.11 SENSOR I/O ERROR CODES 


$0010 DEVICE LOCKED 

$0011 DEVICE ALREADY OPEN 
$0012 A/D OVERANGE 

$0013 CTC TIMER OVERRUN 
$0014 ILLEGAL OPEN MODE 
$0015 A/D TIME-OVERRUN 
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A.4. ABNORMAL-TERMINATION SCREEN 


CS-OS includes a facility for detecting processor TRAPS and providing a 


display 


of 


the pertinent 
troubleshooting. 


information 


There are two types of TRAPS: 


TYPE 1 


includes 


TYPE 2 


Standard processor TRAP 


OPCO 
DIVO 
CHKC 
TRPV 
PRIV 
1010 
us ae 
TR13 
TR14 
? INT 
ABRT 


invalid OP code trap 
divide by zero trap 
check instruction trap 
Trap V instruction 
privilege violation 
illegal instruction 
illegal instruction 
unexpected trap 13 
unexpected trap 14 
unexpected miscellaneous trap 
Abort button interrupt 


Extended information TRAPS 


ADDR 
OPUR 
BUS 

ABUS 
DBUS 
PROT 


DTAK 


MPAR 
POWR 


illegal address trap; word operand on odd address 

spurious interrupt trap 

bus error trap 

address bus error 

data bus error 

memory protection error; attempt to store into 

system memory 

missing DTACK error 

(This message can result from an attempt to 
address memory or devices that are not 
implemented on your machine. Every access must 
terminate with "Data Transfer Acknowledge" or 
DTACK. If it does not, an error message is 
generated. ) 

parity error 

power failure error 


TRAP DISPLAY FORMAT 


FNC=XXXX ADD=XXXXXXXX 


TASK=TASKNAME 


PC=XXXXXX 


INR=XXXX } TYPE 2 ONLY 


XXXX TRAP ERROR 
SSP=XXXXXX 


SR=XXXXA US P=XXXAKX 


available as an aid 


in 
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DO=XXXXXXXX 
D4=XXXXXXXX 
AO=XXXXXXXX 
A4=XXXXXXXX 


D1=XXXXXXXX 
D5=XXXXXXXX 
A1=XXXXXXXX 
A5=XXXXXXXX 


PRESS ANY KEY TO REBOOT 


NOTES 


The 


FNC 
ADD 
INR 


processor function code 
access address at time of trap 
instruction register at time of trap 


D2=XXXXXXXX 
D6=XXXXXXXX 
A2=XKXXXXXXX 
A6=XXXXXXXX 


extended information for type 2 traps is: 
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D3=XXXXXXXX 
D7=XXXXXXXX 
A3=XXXXXXXX 
A7=XXXXXXXX 


A.5 ASSEMBLY ERROR CODES 


A.5.1 ERROR MESSAGES 


Error messages generated during an assembly may originate from the 
assembler or from Pascal or the operating system environment. 
Assembler-generated messages may be of two forms: 


1. WerreeSERROR xxx -- nnnn 
where xxx is the number of the error (defined in the list in this 


appendix), and nnnn is the number of the line where the previous 
error occurred. 


Errors indicate that the assembler is unable to interpret or 
implement the intent of a source line. 


2. Wesel WARNING xxx -- nnnn 


where xxx is the number of the error (defined in the list in this 


appendix), and nnnn is the number of the line where the previous 
error occurred. 


Warnings may indicate possible recoverable errors in the source 
code, or that a more optimal instruction format is possible. 
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ERROR CODE MEANING OF ERROR 


210 
211 
242 
213 
214 
215 
216 
217 
218 
219 
220 
221 


230 
231 
232 
233 
234 
235 
236 
237 
238 
239 


250 
251 
252 
253 


SYNTACTIC ERRORS 


ILLEGAL CHARACTER (IN CONTEXT) 

SIZE CODE/EXTENSION IS INVALID 

SYNTAX ERROR 

SIZE CODE/EXTENSION NOT ALLOWED 

LABEL REQUIRED 

END DIRECTIVE MISSING 

REGISTER RANGES FOR THE MOVEM INSTRUCTION MUST BE SPECIFIED 

IN INCREASING ORDER 

A AND D REGISTERS CAN'T BE INTERMIXED IN A MOVEM REGISTER RANGI 


OPERAND/ADDRESS MODE ERRORS 


MISSING OPERAND(S) 

TOO MANY OPERANDS FOR THIS INSTRUCTION 
IMPROPER TERMINATION OF OPERAND FIELD 
ILLEGAL ADDRESS MODE FOR THIS OPERAND 
ILLEGAL FORWARD REFERENCE 
SYMBOL/EXPRESSION MUST BE ABSOLUTE 
IMMEDIATE SOURCE OPERAND REQUIRED 
ILLEGAL REGISTER FOR THIS INSTRUCTION 
ILLEGAL OPERATION ON A RELATIVE SYMBOL 
MEMORY SHIFTS MAY ONLY BE SINGLE BIT 
INVALID SHIFT COUNT 

INVALID SECTION NUMBER 


SYMBOL DEFINITION 


ATTEMPT TO REDEFINE A RESERVED SYMBOL 

ATTEMPT TO REDEFINE A MACRO; NEW DEFINITION IGNORED 
ATTEMPT TO REDEFINE THE COMMAND LINE LOCATION 
COMMAND LINE LENGTH MUST BE > 0; IGNORED 

REDEFINED SYMBOL 

UNDEFINED SYMBOL 

PHASING ERROR ON PASS2 

START ADDRESS MUST BE IN THIS MODULE, IF SPECIFIED 
UNDEFINED OPERATION (OPCODE) | 

NAMED COMMON SYMBOL MAY NOT BE XDEF 


DATA SIZE RESTRICTIONS 
DISPLACEMENT SIZE ERROR 
VALUE TOO LARGE 


ADDRESS TOO LARGE FOR FORCED ABSOLUTE SHORT 
BYTE MODE NOT ALLOWED FOR THIS OPCODE 
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254 
255 


260 
261 
262 
263 
264 
265 
266 
267 


270 
od 


280 
281 
282 
283 
284 
285 


286 
28/7 
288 
289 
290 
291 
292 


300 
301 


302 
303 
304 
305 


MULTIPLICATION OVERFLOW 
DIVISION BY ZERO 


MACRO ERRORS 


MISPLACED MACRO, MEXIT, OR ENDM DIRECTIVE 

MACRO DEFINITIONS MAY NOT BE NESTED 

ILLEGAL PARAMETER DESIGNATION 

A PERIOD MAY OCCUR ONLY AS THE FIRST CHARACTER IN A MACRO NAME 
MISSING PARAMETER REFERENCE 

TOO MANY PARAMETERS IN THIS MACRO CALL 

REFERENCE PRECEDES MACRO DEFINITION 

OVERFLOW OF INPUT BUFFER DURING MACRO TEXT EXPANSION 


CONDITIONAL ASSEMBLY ERRORS 


UNEXPECTED 'ENDC' 
BAD ENDING TO CONDITIONAL ASSEMBLY STRUCTURE (ENDC EXPECTED) 


STRUCTURED SYNTAX ERRORS 


MISPLACED STRUCTURED CONTROL DIRECTIVE (IGNORED) 
MISSING "ENDI" 

MISSING "“ENDF" 

MISSING "ENDW" 

MISSING "UNTIL" 

UNRESOLVED SYNTAX ERROR IN THE PRECEDING PARAMETERIZED 
STRUCTURED CONTROL DIRECTIVE; RECOVERY ATTEMPTED WITH 
THE CURRENT LINE 

"=" EXPECTED; CHARACTERS UP TO "=" IGNORED 

"<<" EXPECTED; CHARACTERS UP TO "'<" IGNORED 

">" EXPECTED; CHARACTERS UP TO ">" IGNORED 

"DO" EXPECTED: REMAINDER OF LINE IGNORED 

"THEN" EXPECTED; REMAINDER OF LINE IGNORED 

"TO" OR "DOWNTO' EXPECTED; "TO" ASSUMED 

ILLEGAL CONDITION CODE SPECIFIED 


MISCELLANEOUS 


IMPLEMENTATION RESTRICTION 
TOO MANY RELOCATABLE SYMBOLS REFERENCED 
<LINKAGE EDITOR RESTRICTED> 
RELOCATION OF BYTE FIELD ATTEMPTED 
ABSOLUTE SECTION OF LENGTH ZERO DEFINED (LINK ERROR) 
NESTED "INCLUDE" FILES NOT ALLOWED; IGNORED 
FILE NAME REQUIRED IN OPERAND FIELD 
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INTERNAL ERRORS 


400 

® 

e 

e@ 
499 

SOURCE CODE NOT OPTIMAL OR RECOVERABLE ERRORS 

500 | ~~ *~‘THIS BYTE WILL BE SIGN-EXTENDED TO 32 BITS 
501 MISSING PARAMETER REFERENCE IN MACTRO SOURCE 
502 TOO MANY PARAMETERS IN THIS MACRO CALL 
550 THIS BRANCH COULD BE SHORT 
55d THIS ABSOLUTE ADDRESS COULD BE SHORT 


NOTE: If more than 10 errors occur in one line, the message 


seveseveds TOO MANY ERRORS ON THIS LINE 


will be generated. 
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B.O APPENDIX B: INSTRUCTION SET SUMMARY 


This appendix provides a summary of the 68000 instruction set. For 
detailed information, refer to the 68000 16-Bit Microprocessor User's 
Manual. 


INSTRUCTION SET SUMMARY 


a ee ee ee ee ae | | 
| MNEMONIC | OPERATION | ASSEMBLER SYNTAX IX N ZV ¢| 
[[_—_+—__ 
| ABCD |Add Decimal With Extend|ABCD Dy,Dx iy U * U &| 
: | ‘an ~ (Ay) , - (Ax) : ! 
| ADD | Add Binary | ADD <ea>,Dn | 7 eo eae | 
| | (See NOTE 1.) | ADD Dn,<ea> | | 
| | | | | 
| ADDA |Add Address | ADDA <ea>,Dn }- - - - || 
| | | | | 
| ADDI |Add Immediate |DDI #<data>,<ea> | # eo *| 
| | | | | 
| ADDQ |Add Quick | ADDQ #<data>,<ea> je ee 
| | | | | 
| ADDX — |Add Extended | ADDX Dy, Dx [wee eae 
: aa - (Ay) ,- (Ax) ! | 
| AND | AND Logical |AND <ea>,Dn | - * 0 O| 
| | | AND Dn,<ea> | | 
| | | | | 
| ANDI |AND Immediate | ANDI #<data>,<ea> }- * * Q OQ 
| | | | | 
|ASL, ASR |Arithmetic Shift | ASd Dx ,Dy pew eek 
| | |ASd #<data>,Dy | | 
| | |ASd <ea> | | 
pf  ——_ 

Bec |Branch Conditionally  |Bec <label> - - = = = 

| | 
BCHG |Test a Bit and Change |BCHG Dn,<ea> - - * = - 


|BCHG #<data>,<ea> 


| 
| 
| 
| 
| | 
| 
| 
| 
| 


| 
| 
BCLR [Test a Bit and Clear  |BCLR Dn,<ea> - - * 
| 'BCLR #<data>,<ea> 
| | 
BRA |Branch Always |BRA <label> a 
Sane ee ae eA Der aeces Oa een eee 


Instruction Set B-l 


| | | 
| BSET [Test a Bit and Set |BSET Dn,<ea> ie = Z| 
| | |BSET #<data>,<ea> | | 
| | | | | 
| BSR |Branch to Subroutine |BSR <label> |- - - | 
| | | | | 
| BIST |Test a Bit |BTST Dn,<ea> |- - | 
| | |BTST #<data>,<ea> | | 
| | | | | 
| CHK |Check Register |CHK <ea>,Dn | © U| 
| | Against Bounds | | | 
| | | | | 
| CLR |Clear an Operand |CLR <ea> |- O 0 | 
| | | | | 
| CMP | Arithmetic Compare |CMP <ea>,Dn | % | 
| | | | | 
| CMPA | Arithmetic Compare |CMP <ea>,An |- * * | 
| | Address | | | 
| | | | | 
| CMPI |Compare Immediate |CMPI #<data>,<ea> |- * * | 
| | | | | 
| CMPM |Compare Memory |CMPM (Ay)+, (Ax)+ |- * Ww ow a 
i manne spt 
| DBcc |Test Condition and |DBcc Dn,<label> |- - - | 
| | Decrement and Branch | | | 
| | (See NOTE 2.) | | | 
| | | | | 
| DIVS |Signed Divide |DIVS <ea>,Dn |-  % 0| 
| | | | | 
| DIVU |Unsigned Divide |DIVU <ea>,Dn }- * * * Q| 
en | 
| EOR [Exclusive OR Logical  |EOR Dn,<ea> |- * % 0 | 
| ed | | 
| EORI [Exclusive OR Immediate |EORI #<data>,<ea> |-  * 0 | 
| | | | | 
| EXG |Exchange Registers -|EXG Rx,Ry |-  - - | 
| | | | | 
| EXT |Sign Extend |EXT Dn | 0| 
| | | | | 
| JMP | Jump | JMP <ea> | ~ - | 
| | | | | 
| JSR | Jump to Subroutine | JSR <ea> | = - | 


INSTRUCTION SET SUMMARY (continued) 


| 


Instruction Set B-2 


eR TET ERIS DS tay PAOLO SAPNA er SS eT rt rn PE na et rn t= cP ters AUT 


RU I I RN a tia 
| LEA |Load Effective Address |LEA <ea>,An }- - = - -| 
| | | | | 
| LINK |Link and Allocate | LINK An,#<displacement> |- - - - =| 
| | | | 
USRESR. terieal Shite ILSd Dx,Dy Ec * QO %| 
| | |LSd #<data>,Dy | | 
| | |LSd <ea> | | 
eee soat sapien abet \Gs retin SObSeleeellritadtic atime onc booiD 
MOVE [Move Data from Source |MOVE <ea>,<ea> * * OQ O 


| to Destination | 


| & | 
| | | 
| | | | | 
| MOVE |Move to the Status |MOVE <ea>,SR | * wee 
| to SR | Register | | | 
| | | | | 
| MOVE \Move from the STATUS  |MOVE SR,<ea> lI- - e e e{ 
| from SR | Register | | | 
| | | | | 
| MOVE |Move to Condition Codes|Move <ea>,CCR pe we eae 
| to: Ce | | | | 
| | | | | 
| MOVE [Move from Condition |MOVE CCR,<ea> |- - - - =| 
| from CC | Codes (M68010) | | | 
| | | | | 
| MOVE USP |Move User Stack Pointer|MOVE USP, An |= = ee | 
| | |Move An,USP | | 
| | | | | 
| MOVEA |Move Address |MOVEA <ea>,An ly = te | 
| | | | 
| MOVEC [Move to/from Control  |MOVEC Rc,Rn l- - © = 2] 
| | Register (M68010) MOVEC Rn,Rc | | 
| | (See NOTE 3.) | | | 
| | | | | 
| MOVEM |Move Multiple Regis- |MOVEM <register list>,<ea> |- - - - -| 
| | ters (See NOTE 4.) |MOVEM <register list>,<ea> | | 
| | | | | 
| MOVEP |Move Peripheral Data  |MOVEP Dx,d(Ay) ae ee 
| | |MOVEP d(Ay) ,Dx | «| 
| | | | | 
| MOVEQ |\Move Quick |MOVEQ #<data>,Dn |- * * QO O| 
| | | | 
| MOVES i\Move to/from Address  |MOVES <ea>,Rn Je ee | 
| | (M68010) |MOVES Rn,<ea> | | 
bee ee See ten i ieee tai! PLE re cae et nate a i i fae ara a eh 
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INSTRUCTION SET SUMMARY (continued) 


| MULS |Signed Multiply 
| | 
| MULU |Unsigned Multiply 
|_—_________ 7 
NBCD INegate Decimal with 
| Extend 
| 
NEG |Two's Complement 
| Negation 
| 
NEGX |\Negate with Extend 
| 
NOP [No Operation 
| 
NOT | Logical Complement 
| OR |Inclusive OR Logical 
| | 
| | 
| ORI | Inclusive OR Immediate 
|. Cet eae ee Pee ree 
| PEA |Push Effective Address 
RESET |Reset External Devices 
ROL,ROR Rotate without Extend 


ROXL,ROXR| Rotate with Extend 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


RTE Return from Exception 

RTR Return and Restore 
Condition Codes 

RTS Return from Subroutine 


|Subtract Decimal with 


| | Extend 
Yi Ae Sater ee Ape Sie 


|MULS <ea>,Dn ae ee Ae. 10) 
| | | 
[MULU <ea>,Dn l- * * 0 O| 

+ 
| NBCD <ea> | U «*« YU *| 
| NEG <ea> | * eae *| 
| NEGX sea | SB Oe oe * | 
| | | 
| NOP ie, ee a 
| | | 
| NOT <ea> | as ‘e - 0 O | 


|OR <ea>,Dn | 

|OR Dn,<ea> | 

| | | 
l- 3 


|ORI #<data>,<ea> 
|PEA <ea> 


| RESET 
| 
|ROd Dx,Dy 

|ROd #<data>,Dy 
|ROd <ea> 


| 

| 

| 

| 

| 

| 

|ROXd Dx,Dy | 
|ROXd #<data>,Dy | 
|ROXd <ea> | 
—— | 
| RTE | 
| 

| 

| 

| 

| 


| 


| RTR 


| 
| 


|RTS 


|SBCD Dy,Dx 


|SBCD -(Ay),~-(Ax) | | 
es he 8 tad ade he res ee 


Instruction Set B-4 


STOP 


SUB 


INSTRUCTION SET SUMMARY (continued) 


[Set According to 
| Condition 


|Stop Program Execution 


|Subtract Binary 


| 
| 


|Subtract Address 


|Subtract Immediate 


|Subtract Quick 


|Subtract with Extend 


|Swap Register Halves 


[Test and Set an 
| Operand 


| Trap 


[Trap on Overflow 


|Test an Operand 


| Unlink 


|Scc <ea> 


|STOP #<data> 


|SUB <ea>,Dn 
|SUB Dn,<ea> 


|SUBA <ea>,An 


|SUBI #<data>,<ea> 


|SUBQ #<data>,<ea> 


|SUBX Dy ,Dx 
| SUBX - (Ay) >” (Ax) 


|SWAP Dn 


|TAS <ea> 
| 
| 


| TRAP #<vector> 


| TRAPV 


|TST <ea> 


|UNLK An 


ale 
qv 


ERE eats Se Maree ater Were Rene ee Rac Ne ee OTe EET IED UE SESE See Se RE See eR eae Rs ee eal omer eer 


| Instruction Set B-5 


da 


<ea> specifies effective address. 


Re specifies control register. 


Rn - a single register; 
Rn-Rm - a range of consecutive registers with m 
being greater than n. 


<register list> specifies the registers selected for 


transfer to or from memory. <register list> may be: 


Any combination of the above, separated by a slash. 


The assembler accepts DBRA for the F (never true) condition. 


C.0 APPENDIX C: CHARACTER SET 


C.1 The character set recognized by the 68000 Resident Structured 
Assembler is a subset of ASCII (American Standard Code for Information 
Interchange, 1968). The characters listed below are recognized by the 
assembler, and the ASCII code is shown on the following pages. 
1. The uppercase letters A through Z 
2. The integers 0 through 9 
3. Four arithmetic operators: + - * / 
4. The logical operators: >> << & ! 
5. Parentheses used in expressions ( ) 
6. Characters used as special prefixes: 
## (pound sign) specifies the immediate mode of addressing 
S$ (dollar sign) specifies a hexadecimal number 
@ (commercial "at") specifies an octal number 
% (percent) specifies a binary number 
(apostrophe) specifies an ASCII literal character 
7. The special characters used in macros: <> \ @ 
8. Three separating characters: 
SPACE 
, (comma ) 


(period) 


9. A comment in a source statement may include any characters with ASCII 
hexadecimal values from 20 (SP) through 7E (~). 


10. Character used as a special suffix: 


(colon) specifies the end of a label 


Character Set C-l 


ASCII Character Set 


ee gee ee ea ee, te, 


| CHARACTER | 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


RETURN 


SO 


si 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


COMMENTS 
Null or tape feed 
Start of Heading 
Start of Text 
End of Text 


End of Transmission 


Enquire (who are you, WRU) 


Acknowledge 
Bell 

Backspace 
Horizontal Tab 
Line Feed 
Vertical Tab 
Form Feed 


Carriage Return 


Shift Out (to red ribbon) 


Shift In (to black ribbon) 


Data Link Escape 
Device Sieel 1 
Device Control 2 
Device Control 3 


Device Control 4 


| HEX VALUE | 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


00 
O01 
02 
03 
04 
05 
06 
07 
08 


09 


OB 
OC 
OD 
OF 
OF 
10 
11 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
OA | 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


14 


ease ea LT Cae Aner a feet eters eee see ete ote te tote ca aa eee aN: COCOONS TES VENEER PS 
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ASCII Character Set (continued) 


Ree ge ee re eee et eee We ep een ene aa eg ey ee ee 


ee eee ee oe ee 
cr es ee ee eee em meenmeeeeee meer eee ce me ee ee 
re i ee 


+ 


% 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


Negative Acknowledge 


Synchronous idle 


End of Transmission Block 


Cancel 

End of Medium 
Substitute 
Escape, prefix 
File Separator 
Group Separator 
Record Separator 
Unit Separator 
Space or blank 
Exclamation point 
Quotation marks (dieresis) 
Number sign 
Dollar sign 
Percent sign 
Ampersand 


Apostrophe (acute accent, 
closing single quote) 


Opening parenthesis 


Closing parenthesis 


eS SE RS ES SS ES SE ES EE ES ES EE EE SS 
ne ee eo 


15 


16 


17 


18 


19 


1A 


1B 


1C 


1D 


1E 


iF 


20 


21 


aA 


23 


24 


25 


26 


2/ 


28 


29 
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ASCII Character Set (continued) 


SS ES ES A ES ES SS A SS EE SE ES SERRE SEES SO SSS SS A SS ES ES SE NY 


<G —Q &) > fx fy © aaa N oa) +t i) Ne) ™ ore) ON <{ FQ @) om) fx] fry 
N N N N N N oe) om) 70) oa) on) <9) on) on) on) oe) oe) + oa) *y oe) —+y 
ren 
4) 
Je 
a 
@) 
Q, 
coN rr 
iS) os is 
ro ” =} ad 
ro 5S ‘ef foo 4 
or S O 30 3] 
Oo cd oO 3 a & 
G ® =I ae) S S rs) 
a4 0 O dl w e) rc) S 
Yn) ord w ‘[) rc N 9) ~t Va) \O m (oe) ON rc ie, a Oo 
oT a Yn S ce) Oo + 79) ab) “ 
| 5 8} o Oo + 43 ) +4 a) +) ) +4 +) 7) +2 S 3) rt oo .) 
@ 7) & G “ro ~ “4 “cd “rf ae “4 “ “cl a | “ | eo) “i Vv) se] is] ” 
a | & or H ice) 0 00 fo' 9) 0 00 tol) 00 0 60 fot) re = n | ® ® 
v) ro @) rr ® rr “ “cl “i ‘4 “4 “ef “cf “+ “4 “ e) oD) o wo M4 2 
< A. >) ri Ay ww a) (a) i) (a) a) ja) (am) | (am) '@) (Sp) om fx] (és) CY 
ot + A“ ! ~~ 


SE OE EL SS EE SS SS i ES EE ee ene SERS EE cee 
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ASCII Character Set (continued) 


a aa IIR ae a aa ea | 
Commercial at 


oo ES EES EE EE GSS GEES GEE Ge GEE eee 
SS ES EE RE OS ES A A SS ES A ES CS ES EE SE YG ee 


@ 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


Uppercase 
Uppercase 
Uppercase 


Uppercase 


Uppercase 


Uppercase 
Uppercase 
Uppercase 
Uppercase 


Uppercase 


Uppercase 


Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 
Uppercase 


Uppercase 


letter 


letter. 


letter 


letter 


letter 


letter 


letter 


letter 


letter 


letter 


letter 


letter 


letter 


letter 


letter 


letter 


letter 
letter 


letter 


letter 


letter 


A 


R 


S 


T 


U 


54 


40 


41 


42 


43 


Ad, 


45 


46 


47 


48 


49 


4A 


4B 


4C 


4D 


4E 


4F 


50 


51 


52 


53 


55 
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ASCII Character Set (continued) 


V | Uppercase letter V | 56 | 
W ! Uppercase letter W : 57 : 
xX : Uspercage letter X | 58 | 
Y | Uppercase letter Y : 59 : 
Z : Uppercase letter Z | 5A | | 
[ : Opening peackaty : 5B : 
\ ! ee slant : 5C | | 
] ! Closing bracket . 5D i 
: Circumf lex : 5SE : 

= : Underline : SF | 
| : Quotation mark | 60 : 
a | Lowercase letter a : 61 ; 
b- : Lowercase letter b ! 662 : 
c ! Lowercase letter c : 63 | : 
d : Lowercase letter d ! 64 ! 
e ! Lowercase letter e : 65 : 
f : Lowercase letter f : 66 ! 
g | Lowercase letter g ! 67 | 
h ee letter h : 68 ! 
i ! iwercase letter i : 69 : 
j | Lowercase letter j ! 6A | 


- eS TS A SS SS OSS A ES SS EN ES SS SS TS ES ES CT SS SS ee ee 
qereres cece: COE SEmpRGGERED GREED CRORES GES SRE SES ES EN EE A A A i a 


a a ie ee ee 


ASCII Character Set (continued) 


aed Ses Fa ees 


ee 
EE ES ES EE A EE EE ES OE A a ey eS 
ee RE SED TES SE EE EES ES EE EE SES ES SE GR SED eR ee 


k 


DEL 


Lowercase 


Lowercase 


Lowercase 


Lowercase 


Lowercase 


Lowercase 


Lowercase 


Lowercase 


Lowercase. 


Lowercase 


Lowercase 


Lowercase 


Lowercase 


Lowercase 


Lowercase 


Lowercase 


letter 
letter 
letter 
letter 
letter 
letter 
letter 
letter 
letter 
letter 
letter 
letter 
letter 
letter 
letter 


letter 


Opening brace 


Vertical line 


Closing brace 


Equivalent 


Delete 


k 


1 


ee ES a 
OE ES AS AS A A ES ES NS A A SS aS ee 
Se Ee SE RS RE ES SS SE SS SE OE ED SS cE 


6B 


6C 


6D 


6E 


6F 


70 


71 


72 


73 


74 


75 


76 


77 


78 


79 


7A 


7B 


7C 


eS EE eS ee a ee ee 
SS ES A NS RY GS a an 
ee EE Ee ee 


7F 


ESE rEve Ft NOR ci eae (eer a Ee ee See Fe PL (Le eT ee ree ae | 


Character Set C-7 


| D.O APPENDIX D: SAMPLE ASSEMBLER OUTPUT 
| 
| 
| 
| 
| 


1 RARAAAAARARARRARARARRAAARARARAAAAARARAARARARAARATAAARARARARARRARARARRARARERARER 
2 r t 
3 * SAMPLE PROGRAM. THIS PROGRAM RECEIVES CONTROL FROM THE SYSTEM TASK AND . 
4 . MAKES USE OF A SEPARATELY ASSEMBLED SUBROUTINE TO PRINT * 
3 ® TWO MESSAGES. ON COMPLETION IT RETURNS CONTROL BACK TO * 
6 n THE SYSTEM TASK VIA EXIT SYSTEM CALL. THIS EXAMPLE a 
t EXPLICITLY CODES THE SYSTEM CALL TRAP INSTRUCTIONS. ® 
8 z THIS EXAMPLE ALSO MAKES USE OF THE DEFAULT 400 BYTE USER * 
y t STACK WHICH IS AVAILABLE ONLY FROM THE SYSTEM TASK. t 
10 t t 
11 RAAAARARARAARAAAARAAAAAEAARAAARRARAAALAAAAAAARAERAARAPAAAAARARARARAAAARARAARAAR 
12 EZAMMAIN IDNT 1,1 
13 IREF MSCSUB DEFINE EXTERNAL SUBROUTINE 
14.0 00009000 303C0001 MOVE W #€1,D0 | 
13 0 00000004 4EB900000060 JSR MSGSUB CALL SUB TO PRINT MESSAGE t 
16 0 OQICODOA 30300002 MOVE W #2,D0 
17 0 QOOGOOCE 468900000000 JSR MSGSUB CALL SUB TO PRINT MESSAGE 2 
18 0 00000014 
19 0 06000014 4640 TRAP #0 EXIT SYSTEM CALL 
20 0 00000016 0028 DC .V 43 
2 END 
eeeate TOTAL ERRORS (-- 0 
neanet TOTAL WARNINGS Q-- 6 
SYMBOL TABLE LISTING 
SYMBOL NAME SECT VALUE SYMBOL NAHE SECT VALUE 


MSCSUB IREF 8 =6©*® =6—00000000 


Preliminary : Appendix D: Sample Assembler Output D-1 


~ 


R 
Me 
q th 
5 Rg 
6 R 
7 t 
8 
9 MSGPROG 
10 
11 MSCSUB 
12 0 00000006 40F990000022 
130 oCo000C 4E40 
140 QOO0200E Od12 
18 
16 | 
17 0 Q00000LS 4DE9I0COO0ORE 
18 G O000001C 4E40 
19 0 QO00001E 0012 
20 
21 0 00000029. 4£75 
22:0 90000022 
22.9 00090022 424553534147 MSut 
240 QOQGOCZE 4045535341497 MSG2 
25 
atetee TOTAL ERRORS Q-- 9 


eeeeee TOTAL WARNINGS G-- 0 
SYTABCL TABLE LisTING 
SYMBOL NAME SECT VALUE 


MSGI | 00000022 


Z 
MSG? 0 0000002E Z 


MSCGSUB «=sCsNDEF «60s 00000000 


Preliminary 


LDNT 
XDEF 
LE.W 
LEA 
TRAP 
DC. 
END! 
[FY 
LEA 
TRAP 
OCW 
END 
RTS 


SYMBOL NAME 


i.006 
i 


ue 


SAMPLE SUBROUTINE THIS PROGRAM PRINTS ONE OF TWO MESSAGES DEPENDING ON 


THE CONTENTS OF DO.W. 


IT USES THE STRUCTURED PROGRAMMING CONSTRUCTS 
TO DECIDE WHICH MESSAGE (IF ANY) TO PRINT. 


i,t 

MSGSUE 

DQ (EQ) @1- THEN 5 
MSG1,A6 
+0 
ig 


00 (£0) €@2 THEN 5 
MSG2,A6 
#0 
1g 


MESSAGE ONE’ $00 


‘MESSAGE TWU',$¢2 


SECT VALUE 


0 govcdols 
0 99000026 


Appendix D: Sample Assembler Output D-2 


IDENTIEY MSGSUE AS EXTERNAL LABEL 


FRIMSG SYSTEM call 


SUBROUTINE RETURN 


RAERRARAARARERARARAAAARERRARRRRERAARARAAAAKERARRARARRRERARARARARARRARAARARRARARE 


ee ed 


RRPPRAAHAREARAAARAARARARARRARRORERARAARERARRIRARHANPPRRARARARRAARARARAATRA RAR 


E.0 APPENDIX E: EXAMPLES OF LINKED ASSEMBLY-LANGUAGE 


PROGRAMS 
ALINK SCREEN "DIALOG" 


Enter sourc > 1:EXAMMAIN 


Enter output file name 
Enter list file name 


Enter input file, or option, or RETURN to continue :+L 


Enter input file, or option, or RETURN to continue 


Output file : 1:EXAMMAIN.BIN 
Listing to 1:EXAMMAIN.MAP 
Start address is : $ EOOO 


Input file : 1:EXAMMAIN.OBJ 
Input file : 1:MSGPROG.OBJ 


$ 
Code Size = 82 bytes 


Last address used = § E103 


ALINK OUTPUT MAP 


Linking segment ' " (82) 
Initial memavail = 790422 
Final memavail = 790394 


Memory map for segment ' 


: MSGSUB = $ E018 ; 
No: Segment: 51ze: 
0. ' 52 


Load Address is : $ EQOO 
Code Size = 82 
Last address used = $ E103 


:1:MSGPROG 
Enter input file, or option, or RETURN to continue : 


Linked Programs E-1 


F.O APPENDIX F: SYSTEM MEMORY CONSUMPTION 


The System Memory Pool is initialized with 20 pages of storage (1 page = 
1024 bytes). This is enough memory for normal activity on a system 
configured with two floppy drives. As additional resources are added to 
the system, greater demands are made on the system memory pool and 
additional memory must be transferred to the system memory pool using the 
"SET SM" command. In order to judge the amount of memory you should 
tranfer to or from the pool, consider the following rough guidelines: 


SYSTEM SYSTEM POOL 
RESOURCE MEMORY CONSUMPTION 
SENSOR I/O DRIVE 16 PAGES 
GPIB (IEEE-488 )DRIVER 3 PAGES 
ALPHA WINDOWS 1/8 PAGE/WINDOW 
GRAPHICS WINDOWS 1/4 PAGE/WINDOW 
DISK DRIVES: 
OPEN VOLUME 3 PAGES/OPEN VOLUME 
OPEN FILE 1 PAGE/OPEN FILE 
HARD DISK DRIVE 2 PAGES/DRIVE 
FLOPPY DISK DRIVE 0 


As an example, the following command will tranfer 16 pages of memory to 
the sytem pool. 


SET SM=16<CR> 


If it is desirable to invoke the command each time the system is used, the 
above command may be placed in the AUTOEXEC submit file. 


You may issue the SYSMAP command to display the current status of the 
memory pool. 
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